Webhooks

Change a webhook endpoint

Change an endpoint. Only the fields sent are changed. With a dashboard session, changing url or events needs a sign-in within the last 15 minutes; an older session answers 403 REAUTHENTICATION_REQUIRED. Sending the URL and events the endpoint already has is not a change. The same goes for is_active: true on an endpoint with a disabled_reason: turning back on an endpoint Kawaa switched off trusts its destination again. An API key or a connected app is not held to this. is_active: true clears disabled_reason, and is refused with 409 CONFLICT if Kawaa switched the endpoint off while the request was in flight (a revoke, password change or lock that landed after it was authenticated); sending it again afterwards turns it on.

A scoped key needs more than webhooks:write here. A subscription is a way to receive what its events carry, so each requested event also requires the scope that owns that data: verification.completed needs verification:read, verification.failed needs verification:read, job.completed needs verification:read, job.failed needs verification:read, credits.low needs account:read, credits.exhausted needs account:read, blacklist.detected needs deliverability:read, dmarc.failure needs deliverability:read. On an account that can have sub-accounts, credits.low and credits.exhausted additionally require white_label:read, because those deliveries name the sub-account and its label. Missing any of them is a 403 naming each event and the scope it needed, and no webhook is created. An unrestricted key needs none of this. x-kawaa-event-scopes carries the same table in machine-readable form.

put/v1/webhooks/{id}

Request

  • Base URL: https://api.kawaa.com
  • URL: https://api.kawaa.com/v1/webhooks/{id}
  • Auth: one of:
    • API key in header X-Api-Key
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.kawaa.com/oauth/authorize, token URL https://api.kawaa.com/oauth/token, scopes: webhooks:write)

Path parameters

idstring required

Request body

urlstring

Where Kawaa POSTs the callback. HTTPS only: anything else is 400 WEBHOOK_URL_INVALID. No format: uri or anchored scheme pattern is declared on this REQUEST field: the URL is parsed first, which tolerates surrounding whitespace and normalizes the protocol, so " https://x" and "HTTPS://x" are both accepted while either constraint refuses them. HTTPS is required, checked on the PARSED protocol, not on the string you sent. Before storing it, Kawaa replaces the request string with that parsed URL's canonical string, so every response URL is a well-formed URI.

eventsstring[]

Omit the field to leave the subscription alone. Sending it EMPTY is not "unsubscribe from everything": the API answers 400 At least one event is required. Delete the endpoint, or set is_active: false, to stop delivery.

descriptionstring nullable

A note for your own reference. Send null to clear the stored one.

is_activeboolean

Pause or reactivate the webhook. The update allow-lists url, description, events and is_active; anything else is a 400. Turning back on an endpoint that has a disabled_reason clears it, and from a dashboard session needs a sign-in within the last 15 minutes.

webhook_idunknown
created_atunknown
updated_atunknown
last_triggered_atunknown
failure_countunknown
disabled_reasonunknown

Response

Updated.

successunknown required

Example response

{
  "data": {
    "webhook": {
      "webhook_id": "wh_3f9a1c2b4d5e6f7a8b9c0d1e2f3a4b5c"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.