Update a webhook's url and/or events

Updates a webhook's url, its events list, or both — send at least one of the two, or the call returns 400.

Endpoint

PATCH https://api.dairo.app/v1/webhooks/{webhook}

Updates a webhook's url, its events list, or both — send at least one of the two, or the call returns 400. A new url is validated exactly as on create (HTTPS, port 443, public host) and must be unique in your organization, so pointing this webhook at a URL already connected to another endpoint returns 409. A new events array replaces the existing subscription (it is not merged), must contain at least one subscribable event, is de-duplicated, and rejects the synthetic webhook.ping. Returns the updated webhook; changing status is done through the pause and resume actions, not this call. Rate limited to 30 updates per hour; requires the webhooks:write scope.

Scope: webhooks:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X PATCH "https://api.dairo.app/v1/webhooks/webhook" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`webhook`	string	yes	The webhook's ID.

Body

Required, application/json: PatchWebhookRequest.

Field	Type	Required	Description
`url`	string (uri)	no
`events`	array of `"message.received"`, `"message.quarantined"`, `"message.sent"`, `"message.delivered"`, `"message.bounced"`, `"message.complained"`, `"message.delayed"`, `"budget.tripped"`, `"compliance.erasure.completed"`, `"object.scanned"`, `"share_link.opened"`, `"letter.status_changed"`, `"domain.verified"`, `"verification.resolved"`, `"verification.expired"`, `"call.status_changed"`	no

Response

200 Success. Body: application/json, Webhook.

Field	Type	Required	Description
`object`	`"webhook"`	yes
`id`	string (uuid)	yes
`url`	string (uri)	yes
`events`	array of `"message.received"`, `"message.quarantined"`, `"message.sent"`, `"message.delivered"`, `"message.bounced"`, `"message.complained"`, `"message.delayed"`, `"budget.tripped"`, `"compliance.erasure.completed"`, `"object.scanned"`, `"share_link.opened"`, `"letter.status_changed"`, `"domain.verified"`, `"verification.resolved"`, `"verification.expired"`, `"call.status_changed"`	yes
`label`	string or null	no	Optional human label for the endpoint, or null when unlabeled.
`status`	`"active"`, `"paused"`	yes
`createdAt`	string (date-time)	yes
`lastDeliveryAt`	string (date-time) or null	no	Timestamp of the most recent successful webhook delivery, or null before the first successful delivery.
`secondarySecretExpiresAt`	string (date-time) or null	no	End of the dual-secret window after a rotation, or null.
`secondarySecretActive`	boolean	no	Whether deliveries are still signed with the previous secret too.
`consecutiveFailures`	integer	no
`pausedReason`	string or null	no	auto:delivery_failures when the circuit breaker paused the endpoint, else null.
`autoPaused`	boolean	no
`autoPausedAt`	string (date-time) or null	no

200

{
  "object": "webhook",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com",
  "events": [
    "message.received"
  ],
  "label": "production",
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "lastDeliveryAt": "2026-10-19T09:30:00Z",
  "secondarySecretExpiresAt": "2026-10-19T09:30:00Z",
  "secondarySecretActive": true,
  "consecutiveFailures": 0,
  "pausedReason": null,
  "autoPaused": true,
  "autoPausedAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).