Skip to content
DashboardGet API key

Create or replace the project webhook

View .md
PUT

Create or replace the webhook. url must be HTTPS. The signature scheme defaults to v2. A webhook cannot move straight from v1 to v2, or from v2 to v1 (400): a receiver verifying the current scheme would break on the next delivery, so both directions go through v1+v2. Replacing keeps the secret.

Pass disableSenderWebhooks: true to switch off the /v1 sender webhooks of this project in the same call, so each event arrives once.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • urlstring<uri>required

    HTTPS only.

  • eventsstring[]required

    Any event in WebhookEvent. An unknown value is refused with 400 and details.allowed.

    One ofmessage.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.inboundmessage.unsupportedbroadcast.status_changedconversation.newcontact.identity_linkedtemplate.status_changedinvitation.status_changedcall.initiatedcall.answeredcall.completedcall.faileddomain.verifieddomain.failed
    Limitsmin items 1
  • activeboolean
    Defaulttrue
  • signatureVersionstring

    Which X-Zavu-Signature scheme this receiver is sent. The header is t=<unix seconds> followed by the signatures.

    • v1: v1=HMAC_SHA256(secret, body).
    • v2: v2=HMAC_SHA256(secret, "{t}.{body}"). The current scheme, and the default for a new /v2 webhook. It signs the timestamp together with the body.
    • v1+v2: both signatures, sharing one t. The migration setting: a receiver reading either one works.

    Moving straight between v1 and v2, in either direction, returns 400. Set v1+v2 first. See https://www.zavu.dev/docs/guides/receiving-messages/signature-migration

    One ofv1v1+v2v2
  • disableSenderWebhooksboolean

    Switch off the /v1 sender webhooks of this project in the same call, so each event arrives once. They are only switched off (webhookActive: false on /v1); URL, events and secret stay, so /v1 can turn one back on. Off by default: the /v2 webhook is added next to them and both receive every event until you decide. senderWebhooks on the response lists what is still on.

    Defaultfalse

Responses

200Replaced. `secret` is not returned.
  • webhookobjectrequired

    The one webhook for everything in the project. Stored apart from the /v1 project webhook (/v1/invitations/webhook); neither API reads or writes the other's.

    5 properties
    • urlstring<uri>required
    • eventsstring[]required

      Any event in WebhookEvent, including message.*, conversation.new and call.*.

      One ofmessage.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.inboundmessage.unsupportedbroadcast.status_changedconversation.newcontact.identity_linkedtemplate.status_changedinvitation.status_changedcall.initiatedcall.answeredcall.completedcall.faileddomain.verifieddomain.failed
    • activebooleanrequired
    • signatureVersionstringrequired

      Which X-Zavu-Signature scheme this receiver is sent. The header is t=<unix seconds> followed by the signatures.

      • v1: v1=HMAC_SHA256(secret, body).
      • v2: v2=HMAC_SHA256(secret, "{t}.{body}"). The current scheme, and the default for a new /v2 webhook. It signs the timestamp together with the body.
      • v1+v2: both signatures, sharing one t. The migration setting: a receiver reading either one works.

      Moving straight between v1 and v2, in either direction, returns 400. Set v1+v2 first. See https://www.zavu.dev/docs/guides/receiving-messages/signature-migration

      One ofv1v1+v2v2
    • secretstring

      Returned only by PUT /v2/webhook when it creates the webhook, and by POST /v2/webhook/secret.

  • senderWebhooksobject[]required
    3 properties
    • addressstringrequirednullable

      The sender's first address; null for a sender with no connected transport.

    • urlstring<uri>required
    • v1SenderIdstringrequired

      Read-only; the sender to change on /v1.

  • disabledSenderWebhooksintegerrequired

    How many /v1 sender webhooks this call switched off.

201Created. `webhook.secret` is returned once.
  • webhookobjectrequired

    The one webhook for everything in the project. Stored apart from the /v1 project webhook (/v1/invitations/webhook); neither API reads or writes the other's.

    5 properties
    • urlstring<uri>required
    • eventsstring[]required

      Any event in WebhookEvent, including message.*, conversation.new and call.*.

      One ofmessage.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.inboundmessage.unsupportedbroadcast.status_changedconversation.newcontact.identity_linkedtemplate.status_changedinvitation.status_changedcall.initiatedcall.answeredcall.completedcall.faileddomain.verifieddomain.failed
    • activebooleanrequired
    • signatureVersionstringrequired

      Which X-Zavu-Signature scheme this receiver is sent. The header is t=<unix seconds> followed by the signatures.

      • v1: v1=HMAC_SHA256(secret, body).
      • v2: v2=HMAC_SHA256(secret, "{t}.{body}"). The current scheme, and the default for a new /v2 webhook. It signs the timestamp together with the body.
      • v1+v2: both signatures, sharing one t. The migration setting: a receiver reading either one works.

      Moving straight between v1 and v2, in either direction, returns 400. Set v1+v2 first. See https://www.zavu.dev/docs/guides/receiving-messages/signature-migration

      One ofv1v1+v2v2
    • secretstring

      Returned only by PUT /v2/webhook when it creates the webhook, and by POST /v2/webhook/secret.

  • senderWebhooksobject[]required
    3 properties
    • addressstringrequirednullable

      The sender's first address; null for a sender with no connected transport.

    • urlstring<uri>required
    • v1SenderIdstringrequired

      Read-only; the sender to change on /v1.

  • disabledSenderWebhooksintegerrequired

    How many /v1 sender webhooks this call switched off.

400Invalid URL, an event that does not exist (`details.unknown`, `details.allowed`, and `details.errors` naming each by index), or `v1` to `v2` / `v2` to `v1` directly (go through `v1+v2`; `details.errors[0].path` is `["signatureVersion"]`).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring