Webhooks
Create a webhook subscription
Registers an endpoint. Set scope to account to receive events from every profile through one endpoint. The signing secret is returned once.
Required permission: `webhooks:write`
Accepts `profileId` to target a specific profile. Omit it to use the key’s home profile.
POST
/v1/webhookswebhooks:writeRequest
Authorization
Send your API key as a Bearer token in the Authorization header.
Headers
Idempotency-KeystringoptionalA unique key so a retried request is not applied twice. Stored for 24 hours.
Request body
urlstringrequiredHTTPS endpoint that receives POSTs.
eventsenum[]requiredEvent types to subscribe to, or ["*"] for everything.
profileIdstringoptionalProfile to act on. Defaults to the profile the API key was created in.
scopeobjectoptionalDefaults to profile.
Response
Returns 201.
WebhookSubscriptionrequired
secretstringrequiredUse this to verify the CuteDyno-Signature header.
retrySchedulenumber[]requiredRetry delays in seconds.
Errors
Failures use the standard error format.
| Status | Code | When it happens |
|---|---|---|
| 400 | invalid_request | The request body or query string failed validation. The message names the offending field. |
| 401 | invalid_api_key | The key does not exist, was revoked, or is malformed. Keys start with cdyn_live_. |
| 403 | insufficient_permission | The key is missing the scope this endpoint needs, for example posts:write on a readonly key. |
| 429 | rate_limit_exceeded | Too many requests for this key. Honour the Retry-After header before retrying. |
| 500 | internal_error | Something failed on our side. Retry with the same Idempotency-Key; report the requestId if it persists. |