Skip to content
Micro micro
Go to Micro
API Reference

Webhooks

List webhooks
webhooks.list(WebhookListParams**kwargs) -> WebhookListResponse
GET/v2/webhooks/{teamId}
Create a webhook
webhooks.create(WebhookCreateParams**kwargs) -> WebhookWithSecret
POST/v2/webhooks/{teamId}
Get a webhook
webhooks.get(strwebhook_id, WebhookGetParams**kwargs) -> Webhook
GET/v2/webhooks/{teamId}/{webhookId}
Update a webhook
webhooks.update(strwebhook_id, WebhookUpdateParams**kwargs) -> WebhookUpdateResponse
PATCH/v2/webhooks/{teamId}/{webhookId}
Delete a webhook
webhooks.delete(strwebhook_id, WebhookDeleteParams**kwargs)
DELETE/v2/webhooks/{teamId}/{webhookId}
Re-run verification
webhooks.verify(strwebhook_id, WebhookVerifyParams**kwargs) -> WebhookVerifyResponse
POST/v2/webhooks/{teamId}/{webhookId}/verify
Send a test event
webhooks.ping(strwebhook_id, WebhookPingParams**kwargs) -> WebhookPingResponse
POST/v2/webhooks/{teamId}/{webhookId}/ping
List team deliveries
webhooks.list_deliveries(WebhookListDeliveriesParams**kwargs) -> WebhookListDeliveriesResponse
GET/v2/webhooks/{teamId}/deliveries
ModelsExpand Collapse
class Webhook: …

A registered webhook endpoint.

id: str
formatuuid
created_at: datetime
formatdate-time
enabled: bool

Disabled webhooks are skipped at delivery time.

name: str
team_id: str
formatuuid
url: str

Endpoint events are delivered to.

formaturi
verified: bool

True once the endpoint has completed the verification handshake.

description: Optional[str]
updated_at: Optional[datetime]
formatdate-time
verification_token: Optional[str]

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[datetime]
formatdate-time
class WebhookCreate: …

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: str
minLength1
maxLength255
url: str

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

formaturi
description: Optional[str]
maxLength1000
enabled: Optional[bool]
class WebhookDelivery: …

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

created_at: datetime
formatdate-time
delivery_id: str
formatuuid
status: Literal["success", "failed"]
One of the following:
"success"
"failed"
type: Literal["delivery", "verification"]
One of the following:
"delivery"
"verification"
webhook_id: str
formatuuid
attempts: Optional[int]

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

event: Optional[str]

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

status_code: Optional[int]

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

team_id: Optional[str]
formatuuid
updated_at: Optional[datetime]
formatdate-time
url: Optional[str]
class WebhookDeliveryDetail: …

A delivery plus its full attempt timeline.

attempt_history: Optional[List[WebhookDeliveryDetailAttemptHistory]]
attempt: int

1-based attempt number.

created_at: datetime
formatdate-time
status: Literal["success", "failed"]
One of the following:
"success"
"failed"
error: Optional[str]

Failure reason, when status is failed.

request_body: Optional[str]

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

response_body: Optional[str]

Body returned by the endpoint; may be truncated.

status_code: Optional[int]
class WebhookUpdate: …

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

description: Optional[str]
maxLength1000
enabled: Optional[bool]
name: Optional[str]
minLength1
maxLength255
url: Optional[str]
formaturi
class WebhookWithSecret: …

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

secret: str

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[WebhookWithSecretVerification]

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: Literal["pending"]

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

class WebhookListResponse: …
data: List[Webhook]
id: str
formatuuid
created_at: datetime
formatdate-time
enabled: bool

Disabled webhooks are skipped at delivery time.

name: str
team_id: str
formatuuid
url: str

Endpoint events are delivered to.

formaturi
verified: bool

True once the endpoint has completed the verification handshake.

description: Optional[str]
updated_at: Optional[datetime]
formatdate-time
verification_token: Optional[str]

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[datetime]
formatdate-time
class WebhookUpdateResponse: …

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

verification: Optional[WebhookUpdateResponseVerification]

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: Literal["pending"]

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

class WebhookVerifyResponse: …

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

verification: Optional[WebhookVerifyResponseVerification]

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: Literal["pending"]

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

class WebhookPingResponse: …
dispatched: bool
event: str
webhook_id: str
formatuuid
class WebhookListDeliveriesResponse: …
data: List[WebhookDelivery]
created_at: datetime
formatdate-time
delivery_id: str
formatuuid
status: Literal["success", "failed"]
One of the following:
"success"
"failed"
type: Literal["delivery", "verification"]
One of the following:
"delivery"
"verification"
webhook_id: str
formatuuid
attempts: Optional[int]

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

event: Optional[str]

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

status_code: Optional[int]

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

team_id: Optional[str]
formatuuid
updated_at: Optional[datetime]
formatdate-time
url: Optional[str]
next_cursor: Optional[str]

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

WebhooksDeliveries

List webhook deliveries
webhooks.deliveries.list(strwebhook_id, DeliveryListParams**kwargs) -> DeliveryListResponse
GET/v2/webhooks/{teamId}/{webhookId}/deliveries
Get a delivery
webhooks.deliveries.get(strdelivery_id, DeliveryGetParams**kwargs) -> WebhookDeliveryDetail
GET/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}
ModelsExpand Collapse
class DeliveryListResponse: …
data: List[WebhookDelivery]
created_at: datetime
formatdate-time
delivery_id: str
formatuuid
status: Literal["success", "failed"]
One of the following:
"success"
"failed"
type: Literal["delivery", "verification"]
One of the following:
"delivery"
"verification"
webhook_id: str
formatuuid
attempts: Optional[int]

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

event: Optional[str]

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

status_code: Optional[int]

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

team_id: Optional[str]
formatuuid
updated_at: Optional[datetime]
formatdate-time
url: Optional[str]
next_cursor: Optional[str]

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