API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Webhooks

List webhooks

client.webhooks.list(WebhookListParams { teamId } params?, RequestOptionsoptions?): WebhookListResponse { data }

GET/v2/webhooks/{teamId}

Create a webhook

client.webhooks.create(WebhookCreateParams { teamId, name, url, 2 more } params, RequestOptionsoptions?): WebhookWithSecret { secret, verification }

POST/v2/webhooks/{teamId}

Get a webhook

client.webhooks.get(stringwebhookID, WebhookGetParams { teamId } params?, RequestOptionsoptions?): Webhook { id, created_at, enabled, 8 more }

GET/v2/webhooks/{teamId}/{webhookId}

Update a webhook

client.webhooks.update(stringwebhookID, WebhookUpdateParams { teamId, description, enabled, 2 more } params, RequestOptionsoptions?): WebhookUpdateResponse { verification }

PATCH/v2/webhooks/{teamId}/{webhookId}

Delete a webhook

client.webhooks.delete(stringwebhookID, WebhookDeleteParams { teamId } params?, RequestOptionsoptions?): void

DELETE/v2/webhooks/{teamId}/{webhookId}

Re-run verification

client.webhooks.verify(stringwebhookID, WebhookVerifyParams { teamId } params?, RequestOptionsoptions?): WebhookVerifyResponse { verification }

POST/v2/webhooks/{teamId}/{webhookId}/verify

Send a test event

client.webhooks.ping(stringwebhookID, WebhookPingParams { teamId, data, event } params?, RequestOptionsoptions?): WebhookPingResponse { dispatched, event, webhook_id }

POST/v2/webhooks/{teamId}/{webhookId}/ping

List team deliveries

client.webhooks.listDeliveries(WebhookListDeliveriesParams { teamId, cursor, limit, 2 more } params?, RequestOptionsoptions?): WebhookListDeliveriesResponse { data, next_cursor }

GET/v2/webhooks/{teamId}/deliveries

ModelsExpand Collapse

Webhook { id, created_at, enabled, 8 more }

A registered webhook endpoint.

id: string

formatuuid

created_at: string

formatdate-time

enabled: boolean

Disabled webhooks are skipped at delivery time.

name: string

team_id: string

formatuuid

url: string

Endpoint events are delivered to.

formaturi

verified: boolean

True once the endpoint has completed the verification handshake.

description?: string | null

updated_at?: string | null

formatdate-time

verification_token?: string

Stable token replayed to the endpoint (as the micro_hook_token query param) during the verification handshake. The endpoint may check it to confirm the request originated from Micro.

verified_at?: string | null

formatdate-time

WebhookCreate { name, url, description, enabled }

On create, the dispatcher asynchronously runs a verification handshake: it sends a GET to url with micro_hook_mode=subscribe, a one-time micro_hook_challenge, and the webhook’s micro_hook_token. The endpoint must respond 200 and echo the challenge value verbatim in the body; on success the webhook’s verified flag flips to true. A failed handshake does not fail creation — re-run it later via the verify endpoint.

name: string

minLength1

maxLength255

url: string

HTTP(S) endpoint. Rejected if it resolves to a private/internal address.

formaturi

description?: string | null

maxLength1000

enabled?: boolean

WebhookDelivery { created_at, delivery_id, status, 8 more }

A webhook delivery — one logical event delivery to an endpoint, grouping its attempts. Status and status_code reflect the latest attempt.

created_at: string

formatdate-time

delivery_id: string

formatuuid

status: "success" | "failed"

One of the following:

"success"

"failed"

type: "delivery" | "verification"

One of the following:

"delivery"

"verification"

webhook_id: string

formatuuid

attempts?: number | null

Number of attempts made so far (including async retries).

event?: string | null

Event name (e.g. webhook.test); verification for handshake runs.

status_code?: number | null

HTTP status of the latest attempt; null on a transport error.

team_id?: string | null

formatuuid

updated_at?: string | null

formatdate-time

url?: string

WebhookDeliveryDetail extends WebhookDelivery { created_at, delivery_id, status, 8 more } { attempt_history }

A delivery plus its full attempt timeline.

attempt_history?: Array<AttemptHistory>

attempt: number

1-based attempt number.

created_at: string

formatdate-time

status: "success" | "failed"

One of the following:

"success"

"failed"

error?: string | null

Failure reason, when status is failed.

request_body?: string | null

Body sent to the endpoint (delivery only); may be truncated.

response_body?: string | null

Body returned by the endpoint; may be truncated.

status_code?: number | null

WebhookUpdate { description, enabled, name, url }

Partial update. Changing url resets verification and re-runs the handshake.

description?: string | null

maxLength1000

enabled?: boolean

name?: string

minLength1

maxLength255

url?: string

formaturi

WebhookWithSecret extends Webhook { id, created_at, enabled, 8 more } { secret, verification }

Returned ONLY on creation. Includes the signing secret (shown once) and the pending verification status.

secret: string

HMAC signing secret (prefix whsec_). Store it now — it is never returned again. The dispatcher signs each delivered payload with it so your endpoint can verify authenticity.

verification?: Verification { status }

Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its verified flag flips to true on success) to observe the outcome.

status: "pending"

Always pending at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.

WebhookListResponse { data }

data: Array<Webhook { id, created_at, enabled, 8 more } >

id: string

formatuuid

created_at: string

formatdate-time

enabled: boolean

Disabled webhooks are skipped at delivery time.

name: string

team_id: string

formatuuid

url: string

Endpoint events are delivered to.

formaturi

verified: boolean

True once the endpoint has completed the verification handshake.

description?: string | null

updated_at?: string | null

formatdate-time

verification_token?: string

Stable token replayed to the endpoint (as the micro_hook_token query param) during the verification handshake. The endpoint may check it to confirm the request originated from Micro.

verified_at?: string | null

formatdate-time

WebhookUpdateResponse extends Webhook { id, created_at, enabled, 8 more } { verification }

A webhook plus the status of a verification handshake enqueued by this request.

verification?: Verification { status }

Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its verified flag flips to true on success) to observe the outcome.

status: "pending"

Always pending at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.

WebhookVerifyResponse extends Webhook { id, created_at, enabled, 8 more } { verification }

A webhook plus the status of a verification handshake enqueued by this request.

verification?: Verification { status }

Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its verified flag flips to true on success) to observe the outcome.

status: "pending"

Always pending at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.

WebhookPingResponse { dispatched, event, webhook_id }

dispatched: boolean

event: string

webhook_id: string

formatuuid

WebhookListDeliveriesResponse { data, next_cursor }

data: Array<WebhookDelivery { created_at, delivery_id, status, 8 more } >

created_at: string

formatdate-time

delivery_id: string

formatuuid

status: "success" | "failed"

One of the following:

"success"

"failed"

type: "delivery" | "verification"

One of the following:

"delivery"

"verification"

webhook_id: string

formatuuid

attempts?: number | null

Number of attempts made so far (including async retries).

event?: string | null

Event name (e.g. webhook.test); verification for handshake runs.

status_code?: number | null

HTTP status of the latest attempt; null on a transport error.

team_id?: string | null

formatuuid

updated_at?: string | null

formatdate-time

url?: string

next_cursor?: string | null

Pass as cursor to fetch the next page; null when there are no more.

WebhooksDeliveries

List webhook deliveries

client.webhooks.deliveries.list(stringwebhookID, DeliveryListParams { teamId, after, before, 4 more } params?, RequestOptionsoptions?): DeliveryListResponse { data, next_cursor }

GET/v2/webhooks/{teamId}/{webhookId}/deliveries

Get a delivery

client.webhooks.deliveries.get(stringdeliveryID, DeliveryGetParams { teamId, webhookId } params, RequestOptionsoptions?): WebhookDeliveryDetail { attempt_history }

GET/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}

ModelsExpand Collapse

DeliveryListResponse { data, next_cursor }

data: Array<WebhookDelivery { created_at, delivery_id, status, 8 more } >

created_at: string

formatdate-time

delivery_id: string

formatuuid

status: "success" | "failed"

One of the following:

"success"

"failed"

type: "delivery" | "verification"

One of the following:

"delivery"

"verification"

webhook_id: string

formatuuid

attempts?: number | null

Number of attempts made so far (including async retries).

event?: string | null

Event name (e.g. webhook.test); verification for handshake runs.

status_code?: number | null

HTTP status of the latest attempt; null on a transport error.

team_id?: string | null

formatuuid

updated_at?: string | null

formatdate-time

url?: string

next_cursor?: string | null

Pass as cursor to fetch the next page; null when there are no more.