webhook

Methods and types of the `webhook` namespace (`client.webhook` / `bot.webhook`).

Interfaces

CreateWebhookData

Properties

Property	Type	Description
`events`	`WebhookEvent`[]	-
`expiresAt?`	`string` \| `null`	Optional ISO timestamp. Must be in the future when set.
`name`	`string`	-
`url`	`string`	-

CreateWebhookResponse

Extended by

RotateWebhookSecretResponse

Properties

Property	Type	Description
`signingSecret`	`string`	The HMAC signing secret. Returned ONLY here (and from `rotateWebhookSecret`). The server keeps the ciphertext on the row and cannot recover the plaintext later — the customer must capture it now or rotate.
`subscription`	`WebhookSubscription`	-

ListDeliveriesParams

Properties

Property	Type
`cursor?`	`string`
`limit?`	`number`
`status?`	`WebhookAttemptStatus`

ListDeliveriesResponse

Properties

Property	Type
`items`	`WebhookAttempt`[]
`nextCursor`	`string` \| `null`

RotateWebhookSecretResponse

Extends

CreateWebhookResponse

Properties

Property	Type	Description	Inherited from
`signingSecret`	`string`	The HMAC signing secret. Returned ONLY here (and from `rotateWebhookSecret`). The server keeps the ciphertext on the row and cannot recover the plaintext later — the customer must capture it now or rotate.	`CreateWebhookResponse`.`signingSecret`
`subscription`	`WebhookSubscription`	-	`CreateWebhookResponse`.`subscription`

TestWebhookResponse

Properties

Property	Type
`message`	`string`
`queued`	`true`

UpdateWebhookData

Properties

Property	Type	Description
`events?`	`WebhookEvent`[]	-
`expiresAt?`	`string` \| `null`	Pass null to clear an existing expiry; pass a future ISO date to set / extend.
`name?`	`string`	-
`status?`	`"active"` \| `"paused"`	-
`url?`	`string`	-

WebhookAttempt

Properties

Property	Type
`attempt`	`number`
`createdAt`	`string`
`deliveredAt?`	`string` \| `null`
`errorMessage?`	`string` \| `null`
`id`	`string`
`maxAttempts`	`number`
`nextRetryAt?`	`string` \| `null`
`notificationId`	`string`
`responseBody?`	`string` \| `null`
`responseCode?`	`number` \| `null`
`responseHeaders?`	`Record`<`string`, `any`> \| `null`
`scheduledAt`	`string`
`signatureV1`	`string`
`startedAt?`	`string` \| `null`
`status`	`WebhookAttemptStatus`
`subscriptionId`	`string`
`updatedAt`	`string`

WebhookSubscription

Public shape of a webhook subscription. Never includes the signing secret or the encrypted ciphertext — those are server-only fields.

Properties

Property	Type	Description
`appId?`	`string` \| `null`	-
`createdAt`	`string`	-
`createdById`	`string`	-
`events`	`WebhookEvent`[]	-
`expiresAt?`	`string` \| `null`	Optional expiration. When set and in the past, the worker stops fanning new attempts to this subscription, and any in-flight attempts DLQ with a clear reason rather than retrying. Null = no expiry; the subscription delivers indefinitely until manually paused or deleted.
`failedOutAt?`	`string` \| `null`	-
`failedOutReason?`	`string` \| `null`	-
`id`	`string`	-
`lastDeliveryAt?`	`string` \| `null`	-
`lastFailureAt?`	`string` \| `null`	-
`lastSuccessAt?`	`string` \| `null`	-
`name`	`string`	-
`status`	`WebhookSubscriptionStatus`	-
`updatedAt`	`string`	-
`url`	`string`	-
`workspaceId`	`string`	-

Type Aliases

WebhookAttemptStatus

type WebhookAttemptStatus = "pending" | "inflight" | "succeeded" | "failed" | "dlq";

WebhookEvent

type WebhookEvent = 
  | "task.created"
  | "task.updated"
  | "task.deleted"
  | "chat.message.created"
  | "asset.published"
  | "webhook.test";

Wire-format webhook event names. New events are added over time, and payloads only ever gain fields, so receivers pinned to a specific event name keep working as the contract grows.

WebhookSubscriptionStatus

type WebhookSubscriptionStatus = "active" | "paused" | "failedOut";

Functions

default()

function default(client): {
  createWebhook: Promise<CreateWebhookResponse>;
  deleteWebhook: Promise<void>;
  getWebhook: Promise<WebhookSubscription>;
  listWebhookDeliveries: Promise<ListDeliveriesResponse>;
  listWebhooks: Promise<WebhookSubscription[]>;
  replayWebhookDelivery: Promise<{
     attempt: WebhookAttempt;
  }>;
  rotateWebhookSecret: Promise<RotateWebhookSecretResponse>;
  testWebhook: Promise<TestWebhookResponse>;
  updateWebhook: Promise<WebhookSubscription>;
};

Outbound webhook subscription management. Admin-gated server-side by canManageWebhooks. All operations are workspace-scoped — there is no app-owned surface here yet (Phase 3 / OAuth).

Parameters

Parameter	Type
`client`	`default`

Returns

Name	Type	Description
`createWebhook()`	(`workspaceId`, `data`) => `Promise`<`CreateWebhookResponse`>	Create a webhook subscription. The signing secret is in the response's `secret` field — store it immediately, it cannot be retrieved again. Requires `canManageWebhooks` on the workspace.
`deleteWebhook()`	(`workspaceId`, `webhookId`) => `Promise`<`void`>	Delete a webhook subscription. In-flight deliveries continue to the receiver until they exhaust retries; no new deliveries fire. Requires `canManageWebhooks` on the workspace.
`getWebhook()`	(`workspaceId`, `webhookId`) => `Promise`<`WebhookSubscription`>	Fetch a single webhook subscription by id. Requires `canManageWebhooks` on the workspace.
`listWebhookDeliveries()`	( `workspaceId`, `webhookId`, `params?` ) => `Promise`<`ListDeliveriesResponse`>	Paginated list of delivery attempts for a webhook subscription. Useful for diagnosing failures (HTTP status, response body snippet, retry timing). Requires `canManageWebhooks` on the workspace.
`listWebhooks()`	(`workspaceId`) => `Promise`<`WebhookSubscription`[]>	List webhook subscriptions in a workspace. Secrets are never returned. Requires `canManageWebhooks` on the workspace.
`replayWebhookDelivery()`	( `workspaceId`, `webhookId`, `attemptId` ) => `Promise`<{ `attempt`: `WebhookAttempt`; }>	Re-fire a specific past delivery attempt. Useful for confirming a receiver fix without waiting for the next real event. Requires `canManageWebhooks` on the workspace.
`rotateWebhookSecret()`	(`workspaceId`, `webhookId`) => `Promise`<`RotateWebhookSecretResponse`>	Generate a new HMAC signing secret for a subscription and return it once. The old secret is invalidated immediately. Requires `canManageWebhooks` on the workspace.
`testWebhook()`	(`workspaceId`, `webhookId`) => `Promise`<`TestWebhookResponse`>	Fire a synthetic `webhook.test` delivery to the subscription's URL. The receiver gets a small payload they can use to verify their HMAC + parsing setup. Returns immediately; check the delivery log for the outcome.
`updateWebhook()`	( `workspaceId`, `webhookId`, `data` ) => `Promise`<`WebhookSubscription`>	Update a webhook subscription's url, event filter, or active state. Requires `canManageWebhooks` on the workspace.

On this page