Create or replace the project webhook

PUT

webhook

curl --request PUT \
  --url https://api.zavu.dev/v2/webhook \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [],
  "active": true,
  "signatureVersion": "v2",
  "disableSenderWebhooks": false
}
'

import requests

url = "https://api.zavu.dev/v2/webhook"

payload = {
    "url": "<string>",
    "events": [],
    "active": True,
    "signatureVersion": "v2",
    "disableSenderWebhooks": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    events: [],
    active: true,
    signatureVersion: 'v2',
    disableSenderWebhooks: false
  })
};

fetch('https://api.zavu.dev/v2/webhook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zavu.dev/v2/webhook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'events' => [
        
    ],
    'active' => true,
    'signatureVersion' => 'v2',
    'disableSenderWebhooks' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zavu.dev/v2/webhook"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.zavu.dev/v2/webhook")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v2/webhook")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}"

response = http.request(request)
puts response.read_body

{
  "webhook": {
    "url": "<string>",
    "events": [
      "message.queued"
    ],
    "active": true,
    "signatureVersion": "v2",
    "secret": "<string>"
  },
  "senderWebhooks": [
    {
      "address": "<string>",
      "url": "<string>",
      "v1SenderId": "<string>"
    }
  ],
  "disabledSenderWebhooks": 123
}

{
  "webhook": {
    "url": "<string>",
    "events": [
      "message.queued"
    ],
    "active": true,
    "signatureVersion": "v2",
    "secret": "<string>"
  },
  "senderWebhooks": [
    {
      "address": "<string>",
      "url": "<string>",
      "v1SenderId": "<string>"
    }
  ],
  "disabledSenderWebhooks": 123
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

url

string<uri>

required

HTTPS only.

events

enum<string>[]

required

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

Minimum array length: 1

Type of event that triggers the webhook.

Message lifecycle events:

message.queued: Message created and queued for sending. data.status = queued
message.sent: Message accepted by the provider. data.status = sent
message.delivered: Message delivered to recipient. data.status = delivered
message.read: Message was read by the recipient (WhatsApp only). data.status = read
message.failed: Message failed to send. data.status = failed

Inbound events:

message.inbound: New message received from a contact. data.conversationId, the inbox thread id (deep-link with https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}), is sent on email messages only, and is null there on the first message of a brand-new thread. On every other channel it is absent: read it from GET /v2/messages/{messageId}, which always has it, or from conversation.new for a new contact. Reactions are delivered as message.inbound with messageType='reaction'. When the contact replied to (quoted) an earlier message, data.content carries the reply context: replyToMessageId, replyToProviderMessageId, replyToFrom, replyToText, and replyToMessageType. data.providerTimestamp is the provider's original receive time in Unix milliseconds (the moment the channel received the message from the contact — WhatsApp, Telegram, Instagram, Messenger; null for SMS and email). Compare it against the top-level timestamp (when Zavu dispatched the webhook) to detect and ignore delayed deliveries. When the conversation was opened from a Click-to-WhatsApp ad or post, data.referral carries the ad attribution — including ctwaClid, the identifier Meta's Conversions API needs to credit a conversion back to that ad. WhatsApp only, and only on the first message of the thread: it is absent from every later message, so persist it when it arrives.
message.unsupported: Received a message type that is not supported

Broadcast events:

broadcast.status_changed: Broadcast status changed (pending_review, approved, rejected, sending, completed, cancelled)

Other events:

conversation.new: New conversation started with a contact. data carries conversationId (the inbox thread id — deep-link with https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}), the phoneNumber or email key, channel, firstMessageId, firstMessageText, and profileName.
template.status_changed: WhatsApp template approval status changed. data carries templateId, name, previousStatus, currentStatus, rejectionReason, and category — the category Meta currently bills the template under. Meta can recategorize a template (typically UTILITY to MARKETING) at approval or long afterwards, which changes what each message costs; category is how that reaches you. A recategorization with no status change is delivered as this same event, so compare category against what you hold rather than only reacting to currentStatus.

Partner events:

invitation.status_changed: A partner invitation's stored status changed: to in_progress, completed, failed, cancelled, or back to pending when it is resent from the dashboard. A change to the same status sends nothing, and expiry is not a stored change, so no event is sent when an invitation expires. Delivered to the project that created the invitation; a parent project does not receive its sub-accounts' events. data carries invitationId, clientName, clientEmail, connectionType (whatsapp_waba or messenger), previousStatus, and currentStatus. On completed it also carries connectedAccount (channel, id, name), the WhatsApp number or Facebook Page that was linked, and, for WhatsApp, wabaAccountId. On failed it carries failureReason; the invitation link stays usable, so a client can retry it.

Voice Agent events: For every voice event, data carries callId, direction, from, to, status, durationSeconds, endReason, and transcriptAvailable. The terminal events (call.completed, call.failed) additionally carry cost — what the call was billed, in USD, combining telephony and the managed voice pipeline — and currency. They are dispatched after the call is charged, so cost is populated rather than zero; telephony can still be settling on an outbound call, in which case GET /v1/calls/{callId} holds the reconciled figure.

call.initiated: An outbound call was created and is dialing, or an inbound call was received. data.status = ringing
call.answered: The call was answered and the voice agent is connected. data.status = in_progress
call.completed: The call ended after a conversation. data.status = completed; durationSeconds and endReason describe how it ended, and transcriptAvailable indicates whether a transcript can be fetched.
call.failed: The call could not be completed (busy, no answer, canceled, or an error). data.status is the terminal status and endReason explains the cause.

Custom domain events:

domain.verified: A custom email domain passed verification (DKIM, and SPF/DMARC/MAIL FROM if enhanced records are enabled)
domain.failed: A custom email domain failed verification or is partially verified

Available options:

message.queued,

message.sent,

message.delivered,

message.read,

message.failed,

message.inbound,

message.unsupported,

broadcast.status_changed,

conversation.new,

template.status_changed,

invitation.status_changed,

call.initiated,

call.answered,

call.completed,

call.failed,

domain.verified,

domain.failed

active

boolean

default:true

signatureVersion

enum<string>

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://docs.zavu.dev/guides/receiving-messages/signature-migration

Available options:

v1,

v1+v2,

v2

Example:

"v2"

disableSenderWebhooks

boolean

default:false

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.

Response

Replaced. secret is not returned.

webhook

object

required

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.

Show child attributes

senderWebhooks

object[]

required

Show child attributes

disabledSenderWebhooks

integer

required

How many /v1 sender webhooks this call switched off.

⌘I

Create or replace the project webhook

curl --request PUT \
  --url https://api.zavu.dev/v2/webhook \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [],
  "active": true,
  "signatureVersion": "v2",
  "disableSenderWebhooks": false
}
'

import requests

url = "https://api.zavu.dev/v2/webhook"

payload = {
    "url": "<string>",
    "events": [],
    "active": True,
    "signatureVersion": "v2",
    "disableSenderWebhooks": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    events: [],
    active: true,
    signatureVersion: 'v2',
    disableSenderWebhooks: false
  })
};

fetch('https://api.zavu.dev/v2/webhook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zavu.dev/v2/webhook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'events' => [
        
    ],
    'active' => true,
    'signatureVersion' => 'v2',
    'disableSenderWebhooks' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zavu.dev/v2/webhook"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.zavu.dev/v2/webhook")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v2/webhook")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"events\": [],\n  \"active\": true,\n  \"signatureVersion\": \"v2\",\n  \"disableSenderWebhooks\": false\n}"

response = http.request(request)
puts response.read_body

{
  "webhook": {
    "url": "<string>",
    "events": [
      "message.queued"
    ],
    "active": true,
    "signatureVersion": "v2",
    "secret": "<string>"
  },
  "senderWebhooks": [
    {
      "address": "<string>",
      "url": "<string>",
      "v1SenderId": "<string>"
    }
  ],
  "disabledSenderWebhooks": 123
}

{
  "webhook": {
    "url": "<string>",
    "events": [
      "message.queued"
    ],
    "active": true,
    "signatureVersion": "v2",
    "secret": "<string>"
  },
  "senderWebhooks": [
    {
      "address": "<string>",
      "url": "<string>",
      "v1SenderId": "<string>"
    }
  ],
  "disabledSenderWebhooks": 123
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

API v2

API v2 reference

Create or replace the project webhook

Authorizations

Body

Response