# Webhooks ## List webhooks `client.webhooks.list(WebhookListParamsparams?, RequestOptionsoptions?): WebhookListResponse` **get** `/v2/webhooks/{teamId}` Lists the team's webhooks. Signing secrets are never included. ### Parameters - `params: WebhookListParams` - `teamId?: string` ### Returns - `WebhookListResponse` - `data: Array` - `id: string` - `created_at: string` - `enabled: boolean` Disabled webhooks are skipped at delivery time. - `name: string` - `team_id: string` - `url: string` Endpoint events are delivered to. - `verified: boolean` True once the endpoint has completed the verification handshake. - `description?: string | null` - `updated_at?: string | null` - `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` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const webhooks = await client.webhooks.list(); console.log(webhooks.data); ``` #### Response ```json { "data": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "enabled": true, "name": "name", "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com", "verified": true, "description": "description", "updated_at": "2019-12-27T18:11:19.117Z", "verification_token": "verification_token", "verified_at": "2019-12-27T18:11:19.117Z" } ] } ``` ## Create a webhook `client.webhooks.create(WebhookCreateParamsparams, RequestOptionsoptions?): WebhookWithSecret` **post** `/v2/webhooks/{teamId}` Registers a webhook and enqueues an asynchronous verification handshake (run by the dispatcher). The response includes the signing `secret`, shown only this once; `verified` is false until the handshake passes. ### Parameters - `params: WebhookCreateParams` - `teamId?: string` Path param - `name: string` Body param - `url: string` Body param: HTTP(S) endpoint. Rejected if it resolves to a private/internal address. - `description?: string | null` Body param - `enabled?: boolean` Body param ### Returns - `WebhookWithSecret extends Webhook` 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 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. - `"pending"` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const webhookWithSecret = await client.webhooks.create({ name: 'x', url: 'https://example.com' }); console.log(webhookWithSecret); ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "enabled": true, "name": "name", "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com", "verified": true, "description": "description", "updated_at": "2019-12-27T18:11:19.117Z", "verification_token": "verification_token", "verified_at": "2019-12-27T18:11:19.117Z", "secret": "secret", "verification": { "status": "pending" } } ``` ## Get a webhook `client.webhooks.get(stringwebhookID, WebhookGetParamsparams?, RequestOptionsoptions?): Webhook` **get** `/v2/webhooks/{teamId}/{webhookId}` Get a webhook ### Parameters - `webhookID: string` - `params: WebhookGetParams` - `teamId?: string` ### Returns - `Webhook` A registered webhook endpoint. - `id: string` - `created_at: string` - `enabled: boolean` Disabled webhooks are skipped at delivery time. - `name: string` - `team_id: string` - `url: string` Endpoint events are delivered to. - `verified: boolean` True once the endpoint has completed the verification handshake. - `description?: string | null` - `updated_at?: string | null` - `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` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const webhook = await client.webhooks.get('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(webhook.id); ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "enabled": true, "name": "name", "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com", "verified": true, "description": "description", "updated_at": "2019-12-27T18:11:19.117Z", "verification_token": "verification_token", "verified_at": "2019-12-27T18:11:19.117Z" } ``` ## Update a webhook `client.webhooks.update(stringwebhookID, WebhookUpdateParamsparams, RequestOptionsoptions?): WebhookUpdateResponse` **patch** `/v2/webhooks/{teamId}/{webhookId}` Updates mutable fields. Changing `url` resets verification and re-runs the handshake. ### Parameters - `webhookID: string` - `params: WebhookUpdateParams` - `teamId?: string` Path param - `description?: string | null` Body param - `enabled?: boolean` Body param - `name?: string` Body param - `url?: string` Body param ### Returns - `WebhookUpdateResponse extends Webhook` A webhook plus the status of a verification handshake enqueued by this request. - `verification?: Verification` 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. - `"pending"` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const webhook = await client.webhooks.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(webhook); ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "enabled": true, "name": "name", "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com", "verified": true, "description": "description", "updated_at": "2019-12-27T18:11:19.117Z", "verification_token": "verification_token", "verified_at": "2019-12-27T18:11:19.117Z", "verification": { "status": "pending" } } ``` ## Delete a webhook `client.webhooks.delete(stringwebhookID, WebhookDeleteParamsparams?, RequestOptionsoptions?): void` **delete** `/v2/webhooks/{teamId}/{webhookId}` Delete a webhook ### Parameters - `webhookID: string` - `params: WebhookDeleteParams` - `teamId?: string` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); await client.webhooks.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); ``` ## Re-run verification `client.webhooks.verify(stringwebhookID, WebhookVerifyParamsparams?, RequestOptionsoptions?): WebhookVerifyResponse` **post** `/v2/webhooks/{teamId}/{webhookId}/verify` Re-runs the GET challenge/echo handshake against the webhook's url and updates its verified state. ### Parameters - `webhookID: string` - `params: WebhookVerifyParams` - `teamId?: string` ### Returns - `WebhookVerifyResponse extends Webhook` A webhook plus the status of a verification handshake enqueued by this request. - `verification?: Verification` 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. - `"pending"` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const response = await client.webhooks.verify('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(response); ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "enabled": true, "name": "name", "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com", "verified": true, "description": "description", "updated_at": "2019-12-27T18:11:19.117Z", "verification_token": "verification_token", "verified_at": "2019-12-27T18:11:19.117Z", "verification": { "status": "pending" } } ``` ## Send a test event `client.webhooks.ping(stringwebhookID, WebhookPingParamsparams?, RequestOptionsoptions?): WebhookPingResponse` **post** `/v2/webhooks/{teamId}/{webhookId}/ping` Fire-and-forget test delivery through the async dispatcher. The webhook must be enabled and verified. ### Parameters - `webhookID: string` - `params: WebhookPingParams` - `teamId?: string` Path param - `data?: Record` Body param: Arbitrary JSON payload body. - `event?: string` Body param: Event name to send. ### Returns - `WebhookPingResponse` - `dispatched: boolean` - `event: string` - `webhook_id: string` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const response = await client.webhooks.ping('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(response.webhook_id); ``` #### Response ```json { "dispatched": true, "event": "event", "webhook_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } ``` ## List team deliveries `client.webhooks.listDeliveries(WebhookListDeliveriesParamsparams?, RequestOptionsoptions?): WebhookListDeliveriesResponse` **get** `/v2/webhooks/{teamId}/deliveries` Account-wide delivery feed across all of the team's webhooks, newest first. ### Parameters - `params: WebhookListDeliveriesParams` - `teamId?: string` Path param - `cursor?: string` Query param: Opaque cursor from a previous response's `next_cursor`. - `limit?: number` Query param: Page size (1–100, default 25). - `status?: "success" | "failed"` Query param: Filter by outcome. - `"success"` - `"failed"` - `type?: "delivery" | "verification" | "all"` Query param: Filter by run type. Defaults to `delivery` (event deliveries). Pass `all` to include verification handshakes. - `"delivery"` - `"verification"` - `"all"` ### Returns - `WebhookListDeliveriesResponse` - `data: Array` - `created_at: string` - `delivery_id: string` - `status: "success" | "failed"` - `"success"` - `"failed"` - `type: "delivery" | "verification"` - `"delivery"` - `"verification"` - `webhook_id: string` - `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` - `updated_at?: string | null` - `url?: string` - `next_cursor?: string | null` Pass as `cursor` to fetch the next page; null when there are no more. ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const response = await client.webhooks.listDeliveries(); console.log(response.data); ``` #### Response ```json { "data": [ { "created_at": "2019-12-27T18:11:19.117Z", "delivery_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "status": "success", "type": "delivery", "webhook_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "attempts": 0, "event": "event", "status_code": 0, "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ], "next_cursor": "next_cursor" } ``` ## Domain Types ### Webhook - `Webhook` A registered webhook endpoint. - `id: string` - `created_at: string` - `enabled: boolean` Disabled webhooks are skipped at delivery time. - `name: string` - `team_id: string` - `url: string` Endpoint events are delivered to. - `verified: boolean` True once the endpoint has completed the verification handshake. - `description?: string | null` - `updated_at?: string | null` - `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` ### Webhook Create - `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: string` - `url: string` HTTP(S) endpoint. Rejected if it resolves to a private/internal address. - `description?: string | null` - `enabled?: boolean` ### Webhook Delivery - `WebhookDelivery` A webhook delivery — one logical event delivery to an endpoint, grouping its attempts. Status and status_code reflect the latest attempt. - `created_at: string` - `delivery_id: string` - `status: "success" | "failed"` - `"success"` - `"failed"` - `type: "delivery" | "verification"` - `"delivery"` - `"verification"` - `webhook_id: string` - `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` - `updated_at?: string | null` - `url?: string` ### Webhook Delivery Detail - `WebhookDeliveryDetail extends WebhookDelivery` A delivery plus its full attempt timeline. - `attempt_history?: Array` - `attempt: number` 1-based attempt number. - `created_at: string` - `status: "success" | "failed"` - `"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` ### Webhook Update - `WebhookUpdate` Partial update. Changing `url` resets verification and re-runs the handshake. - `description?: string | null` - `enabled?: boolean` - `name?: string` - `url?: string` ### Webhook With Secret - `WebhookWithSecret extends Webhook` 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 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. - `"pending"` ### Webhook List Response - `WebhookListResponse` - `data: Array` - `id: string` - `created_at: string` - `enabled: boolean` Disabled webhooks are skipped at delivery time. - `name: string` - `team_id: string` - `url: string` Endpoint events are delivered to. - `verified: boolean` True once the endpoint has completed the verification handshake. - `description?: string | null` - `updated_at?: string | null` - `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` ### Webhook Update Response - `WebhookUpdateResponse extends Webhook` A webhook plus the status of a verification handshake enqueued by this request. - `verification?: Verification` 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. - `"pending"` ### Webhook Verify Response - `WebhookVerifyResponse extends Webhook` A webhook plus the status of a verification handshake enqueued by this request. - `verification?: Verification` 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. - `"pending"` ### Webhook Ping Response - `WebhookPingResponse` - `dispatched: boolean` - `event: string` - `webhook_id: string` ### Webhook List Deliveries Response - `WebhookListDeliveriesResponse` - `data: Array` - `created_at: string` - `delivery_id: string` - `status: "success" | "failed"` - `"success"` - `"failed"` - `type: "delivery" | "verification"` - `"delivery"` - `"verification"` - `webhook_id: string` - `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` - `updated_at?: string | null` - `url?: string` - `next_cursor?: string | null` Pass as `cursor` to fetch the next page; null when there are no more. # Deliveries ## List webhook deliveries `client.webhooks.deliveries.list(stringwebhookID, DeliveryListParamsparams?, RequestOptionsoptions?): DeliveryListResponse` **get** `/v2/webhooks/{teamId}/{webhookId}/deliveries` An endpoint's deliveries, newest first, with optional status / type / time-range filters and cursor pagination. ### Parameters - `webhookID: string` - `params: DeliveryListParams` - `teamId?: string` Path param - `after?: string` Query param: Only deliveries at or after this ISO-8601 timestamp. - `before?: string` Query param: Only deliveries at or before this ISO-8601 timestamp. - `cursor?: string` Query param: Opaque cursor from a previous response's `next_cursor`. - `limit?: number` Query param: Page size (1–100, default 25). - `status?: "success" | "failed"` Query param: Filter by outcome. - `"success"` - `"failed"` - `type?: "delivery" | "verification" | "all"` Query param: Filter by run type. Defaults to `delivery` (event deliveries). Pass `all` to include verification handshakes. - `"delivery"` - `"verification"` - `"all"` ### Returns - `DeliveryListResponse` - `data: Array` - `created_at: string` - `delivery_id: string` - `status: "success" | "failed"` - `"success"` - `"failed"` - `type: "delivery" | "verification"` - `"delivery"` - `"verification"` - `webhook_id: string` - `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` - `updated_at?: string | null` - `url?: string` - `next_cursor?: string | null` Pass as `cursor` to fetch the next page; null when there are no more. ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const deliveries = await client.webhooks.deliveries.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(deliveries.data); ``` #### Response ```json { "data": [ { "created_at": "2019-12-27T18:11:19.117Z", "delivery_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "status": "success", "type": "delivery", "webhook_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "attempts": 0, "event": "event", "status_code": 0, "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ], "next_cursor": "next_cursor" } ``` ## Get a delivery `client.webhooks.deliveries.get(stringdeliveryID, DeliveryGetParamsparams, RequestOptionsoptions?): WebhookDeliveryDetail` **get** `/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}` A single delivery plus its full attempt timeline (including async retries). ### Parameters - `deliveryID: string` - `params: DeliveryGetParams` - `teamId?: string` - `webhookId: string` ### Returns - `WebhookDeliveryDetail extends WebhookDelivery` A delivery plus its full attempt timeline. - `attempt_history?: Array` - `attempt: number` 1-based attempt number. - `created_at: string` - `status: "success" | "failed"` - `"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` ### Example ```typescript import Micro from '@micro-so/sdk'; const client = new Micro({ teamID: 'My Team ID', apiKey: process.env['MICRO_API_KEY'], // This is the default and can be omitted }); const webhookDeliveryDetail = await client.webhooks.deliveries.get( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { webhookId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }, ); console.log(webhookDeliveryDetail); ``` #### Response ```json { "created_at": "2019-12-27T18:11:19.117Z", "delivery_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "status": "success", "type": "delivery", "webhook_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "attempts": 0, "event": "event", "status_code": 0, "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url", "attempt_history": [ { "attempt": 0, "created_at": "2019-12-27T18:11:19.117Z", "status": "success", "error": "error", "request_body": "request_body", "response_body": "response_body", "status_code": 0 } ] } ``` ## Domain Types ### Delivery List Response - `DeliveryListResponse` - `data: Array` - `created_at: string` - `delivery_id: string` - `status: "success" | "failed"` - `"success"` - `"failed"` - `type: "delivery" | "verification"` - `"delivery"` - `"verification"` - `webhook_id: string` - `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` - `updated_at?: string | null` - `url?: string` - `next_cursor?: string | null` Pass as `cursor` to fetch the next page; null when there are no more.