---
title: "Send lifecycle events to a URL."
method: POST
path: "/v1/webhooks"
tags: ["observability"]
---

# Send lifecycle events to a URL.

`POST /v1/webhooks`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/webhooks`
- Auth: HTTP bearer

Returns the webhook with its signing secret, shown this once (and to a retry by the same key with the same Idempotency-Key within 24 hours, until the secret is rotated). Each delivery is a POST of JSON {id, type, createdAt, data} with a Runtime-Signature header, t=<unix seconds>,v1=<hex HMAC-SHA256 of `${t}.${body}` with the secret>; verify it with verifyWebhook in either SDK. Retries back off over about three days (10 attempts); answer 2xx within 10 seconds. At most 16 webhooks an account.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: An https URL on the public internet.
  - `description` string
  - `events` string[]: Which events to send; ["*"], the default, sends every type, including ones added later.

## Response `200`

Success

- object
  - `id` string, required
  - `url` string, required
  - `description` string, nullable
  - `events` string[], required
  - `enabled` boolean, required
  - `secretHint` string, required
  - `secret` string: The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again.
  - `previousSecretExpiresAt` string, nullable
  - `createdAt` string
  - `updatedAt` string
  - `lastSuccessAt` string, nullable
  - `lastFailureAt` string, nullable
  - `failingSince` string, nullable

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)