Skip to content
Micro micro
Go to Micro
API Reference

Webhooks

List webhooks
client.Webhooks.List(ctx, query) (*WebhookListResponse, error)
GET/v2/webhooks/{teamId}
Create a webhook
client.Webhooks.New(ctx, params) (*WebhookWithSecret, error)
POST/v2/webhooks/{teamId}
Get a webhook
client.Webhooks.Get(ctx, webhookID, query) (*Webhook, error)
GET/v2/webhooks/{teamId}/{webhookId}
Update a webhook
client.Webhooks.Update(ctx, webhookID, params) (*WebhookUpdateResponse, error)
PATCH/v2/webhooks/{teamId}/{webhookId}
Delete a webhook
client.Webhooks.Delete(ctx, webhookID, body) error
DELETE/v2/webhooks/{teamId}/{webhookId}
Re-run verification
client.Webhooks.Verify(ctx, webhookID, body) (*WebhookVerifyResponse, error)
POST/v2/webhooks/{teamId}/{webhookId}/verify
Send a test event
client.Webhooks.Ping(ctx, webhookID, params) (*WebhookPingResponse, error)
POST/v2/webhooks/{teamId}/{webhookId}/ping
List team deliveries
client.Webhooks.ListDeliveries(ctx, params) (*WebhookListDeliveriesResponse, error)
GET/v2/webhooks/{teamId}/deliveries
ModelsExpand Collapse
type Webhook struct{…}

A registered webhook endpoint.

ID string
formatuuid
CreatedAt Time
formatdate-time
Enabled bool

Disabled webhooks are skipped at delivery time.

Name string
TeamID string
formatuuid
URL string

Endpoint events are delivered to.

formaturi
Verified bool

True once the endpoint has completed the verification handshake.

Description stringOptional
UpdatedAt TimeOptional
formatdate-time
VerificationToken stringOptional

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.

VerifiedAt TimeOptional
formatdate-time
type WebhookCreate struct{…}

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 stringOptional
maxLength1000
Enabled boolOptional
type WebhookDelivery struct{…}

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

CreatedAt Time
formatdate-time
DeliveryID string
formatuuid
Status WebhookDeliveryStatus
One of the following:
const WebhookDeliveryStatusSuccess WebhookDeliveryStatus = "success"
const WebhookDeliveryStatusFailed WebhookDeliveryStatus = "failed"
Type WebhookDeliveryType
One of the following:
const WebhookDeliveryTypeDelivery WebhookDeliveryType = "delivery"
const WebhookDeliveryTypeVerification WebhookDeliveryType = "verification"
WebhookID string
formatuuid
Attempts int64Optional

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

Event stringOptional

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

StatusCode int64Optional

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

TeamID stringOptional
formatuuid
UpdatedAt TimeOptional
formatdate-time
URL stringOptional
type WebhookDeliveryDetail struct{…}

A delivery plus its full attempt timeline.

AttemptHistory []WebhookDeliveryDetailAttemptHistoryOptional
Attempt int64

1-based attempt number.

CreatedAt Time
formatdate-time
Status WebhookDeliveryDetailAttemptHistoryStatus
One of the following:
const WebhookDeliveryDetailAttemptHistoryStatusSuccess WebhookDeliveryDetailAttemptHistoryStatus = "success"
const WebhookDeliveryDetailAttemptHistoryStatusFailed WebhookDeliveryDetailAttemptHistoryStatus = "failed"
Error stringOptional

Failure reason, when status is failed.

RequestBody stringOptional

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

ResponseBody stringOptional

Body returned by the endpoint; may be truncated.

StatusCode int64Optional
type WebhookUpdate struct{…}

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

Description stringOptional
maxLength1000
Enabled boolOptional
Name stringOptional
minLength1
maxLength255
URL stringOptional
formaturi
type WebhookWithSecret struct{…}

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 WebhookWithSecretVerificationOptional

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 WebhookWithSecretVerificationStatus

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

WebhooksDeliveries

List webhook deliveries
client.Webhooks.Deliveries.List(ctx, webhookID, params) (*WebhookDeliveryListResponse, error)
GET/v2/webhooks/{teamId}/{webhookId}/deliveries
Get a delivery
client.Webhooks.Deliveries.Get(ctx, webhookID, deliveryID, query) (*WebhookDeliveryDetail, error)
GET/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}