Webhooks

Register a webhook endpoint

Kawaa POSTs to url when one of events happens, signing each delivery. Past the plan's endpoint cap this answers 403 PLAN_LIMIT_EXCEEDED. With a dashboard session, the session must have signed in within the last 15 minutes; an older one answers 403 REAUTHENTICATION_REQUIRED (sign in again, then retry). An API key or a connected app is not held to this. The write is conditioned on the creating API key (or the key a dashboard session was signed in with, or a connected app's access token) still being active, so a request made just before that credential was revoked answers 401 API_KEY_REVOKED and creates nothing. A password change, reset, account lock or white-label sub-account key reset that lands while the request is in progress answers 409 CONFLICT; nothing is created.

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.

post/v1/webhooks

Request

  • Base URL: https://api.kawaa.com
  • URL: https://api.kawaa.com/v1/webhooks
  • 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)

Request body

urlstring required

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[] required
descriptionstring nullable

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

Response

Registered. This endpoint's initial signing secret is returned once; no read operation returns it, but the rotation operation can replace a lost or exposed value.

successunknown required

Example response

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

Changes

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