Cowdidocs
API ReferenceWebhooks

Register a webhook

POST
/v1/webhooks

Registers a webhook and mints its first signing key. The signing secret is in the response and is never retrievable again. The URL must use https and must not resolve inside a private network, unless it matches a configured in-cluster host suffix. Requires the org:connect:write permission. Returns 400 when the URL is invalid or an events entry is not in the published vocabulary, and 409 when the name or URL already belongs to another webhook.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Request Body

application/json

Request to register a webhook.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "name": "sales-app",    "description": "Order updates for the sales app",    "url": "https://sales.example.com/hooks/cowdi",    "events": [      "approval.outcome"    ],    "timeout": "PT5S"  }'
{  "id": "550e8400-e29b-41d4-a716-446655440000",  "name": "sales-app",  "description": "Order updates for the sales app",  "url": "https://sales.example.com/hooks/cowdi",  "status": "ACTIVE",  "events": [    "approval.outcome"  ],  "timeout": "PT5S",  "signing_keys": [    {      "id": "550e8400-e29b-41d4-a716-446655440001",      "secret": "whsec_examplekey_abc123def456ghi789",      "masked_secret": "whsec_...a1b2",      "created_at": "2026-09-01T10:15:30Z"    }  ],  "created_at": "2026-09-01T10:15:30Z",  "updated_at": "2026-10-15T14:22:00Z"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List webhooks GET

Lists the webhooks registered by the caller's organization, newest first. The page uses keyset cursors: follow the `next` and `prev` links in the response. Requires the `org:connect:read` permission.

List deliveries GET

Lists every attempt this platform made to call a webhook of the caller's organization, newest first, with the body that was sent and whatever the receiver answered. Requires the `org:connect:read` permission. Narrow it with `webhook_id`, `status`, `event_type` and a `created_from`/`created_until` window. The window is over when the delivery was created; `sent_at` on each row says when the last attempt ran.