Skip to content
Micro micro
Go to Micro
API Reference

Webhooks

List webhooks
GET/v2/webhooks/{teamId}
Create a webhook
POST/v2/webhooks/{teamId}
Get a webhook
GET/v2/webhooks/{teamId}/{webhookId}
Update a webhook
PATCH/v2/webhooks/{teamId}/{webhookId}
Delete a webhook
DELETE/v2/webhooks/{teamId}/{webhookId}
Re-run verification
POST/v2/webhooks/{teamId}/{webhookId}/verify
Send a test event
POST/v2/webhooks/{teamId}/{webhookId}/ping
List team deliveries
GET/v2/webhooks/{teamId}/deliveries
ModelsExpand Collapse
Webhook object { 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: optional string
updated_at: optional string
formatdate-time
verification_token: optional 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: optional string
formatdate-time
WebhookCreate object { 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: optional string
maxLength1000
enabled: optional boolean
WebhookDelivery object { 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" or "failed"
One of the following:
"success"
"failed"
type: "delivery" or "verification"
One of the following:
"delivery"
"verification"
webhook_id: string
formatuuid
attempts: optional number

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

event: optional string

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

status_code: optional number

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

team_id: optional string
formatuuid
updated_at: optional string
formatdate-time
url: optional string
WebhookDeliveryDetail = WebhookDelivery { created_at, delivery_id, status, 8 more }

A delivery plus its full attempt timeline.

attempt_history: optional array of object { attempt, created_at, status, 4 more }
attempt: number

1-based attempt number.

created_at: string
formatdate-time
status: "success" or "failed"
One of the following:
"success"
"failed"
error: optional string

Failure reason, when status is failed.

request_body: optional string

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

response_body: optional string

Body returned by the endpoint; may be truncated.

status_code: optional number
WebhookUpdate object { description, enabled, name, url }

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

description: optional string
maxLength1000
enabled: optional boolean
name: optional string
minLength1
maxLength255
url: optional string
formaturi
WebhookWithSecret = Webhook { id, created_at, enabled, 8 more }

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: optional object { 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 object { data }
data: array of 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: optional string
updated_at: optional string
formatdate-time
verification_token: optional 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: optional string
formatdate-time
WebhookUpdateResponse = Webhook { id, created_at, enabled, 8 more }

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

verification: optional object { 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 = Webhook { id, created_at, enabled, 8 more }

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

verification: optional object { 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 object { dispatched, event, webhook_id }
dispatched: boolean
event: string
webhook_id: string
formatuuid
WebhookListDeliveriesResponse object { data, next_cursor }
data: array of WebhookDelivery { created_at, delivery_id, status, 8 more }
created_at: string
formatdate-time
delivery_id: string
formatuuid
status: "success" or "failed"
One of the following:
"success"
"failed"
type: "delivery" or "verification"
One of the following:
"delivery"
"verification"
webhook_id: string
formatuuid
attempts: optional number

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

event: optional string

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

status_code: optional number

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

team_id: optional string
formatuuid
updated_at: optional string
formatdate-time
url: optional string
next_cursor: optional string

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

WebhooksDeliveries

List webhook deliveries
GET/v2/webhooks/{teamId}/{webhookId}/deliveries
Get a delivery
GET/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}
ModelsExpand Collapse
DeliveryListResponse object { data, next_cursor }
data: array of WebhookDelivery { created_at, delivery_id, status, 8 more }
created_at: string
formatdate-time
delivery_id: string
formatuuid
status: "success" or "failed"
One of the following:
"success"
"failed"
type: "delivery" or "verification"
One of the following:
"delivery"
"verification"
webhook_id: string
formatuuid
attempts: optional number

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

event: optional string

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

status_code: optional number

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

team_id: optional string
formatuuid
updated_at: optional string
formatdate-time
url: optional string
next_cursor: optional string

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