Webhooks

Webhooks allow your application to receive real-time notifications when events occur, such as incoming messages, delivery status changes, or partner invitation updates.

Zavu supports two types of webhooks:

• Sender Webhooks: Receive events for a specific sender (messages, conversations)
• Project Webhooks: Receive project-level events (partner invitations)

Project Webhooks

Project webhooks are ideal for receiving notifications about project-level events, such as when a partner invitation is completed. This is particularly useful if you're using the Partner Invitations API to onboard clients.

A project webhook receives events for its own project only. If you onboard each client in a sub-account, configure the webhook with that sub-account's API key: the parent project's webhook does not receive events from its sub-accounts.

Via Dashboard

1. Go to Dashboard and select your project
2. Navigate to Webhooks in the sidebar
3. In the "Project Webhook" section, click Configure
4. Enter your webhook URL and select the events you want to receive
5. Save - you'll receive a signing secret

Via API

Configure a project webhook using the invitations API:

cURLCopy
curl -X POST https://api.zavu.dev/v1/invitations/webhook \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/zavu",
    "events": ["invitation.status_changed"]
  }'

Response:

JSONCopy
{
  "webhook": {
    "url": "https://your-app.com/webhooks/zavu",
    "events": ["invitation.status_changed"],
    "secret": "whsec_abc123def456...",
    "active": true
  }
}

Managing Project Webhooks

Get current configuration:

cURLCopy
curl https://api.zavu.dev/v1/invitations/webhook \
  -H "Authorization: Bearer zv_live_xxx"

Update webhook: only works on a webhook created with POST first. Updating one that does not exist returns 400.

cURLCopy
curl -X PATCH https://api.zavu.dev/v1/invitations/webhook \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-url.com/webhooks",
    "active": true
  }'

Remove webhook:

cURLCopy
curl -X DELETE https://api.zavu.dev/v1/invitations/webhook \
  -H "Authorization: Bearer zv_live_xxx"

Project Webhook Events

Project Webhook Payload

JSONCopy
{
  "id": "evt_1234567890_abc123",
  "type": "invitation.status_changed",
  "timestamp": 1705312200000,
  "projectId": "prj_xyz789",
  "data": {
    "invitationId": "inv_abc123",
    "clientName": "John Doe",
    "clientEmail": "john@example.com",
    "connectionType": "whatsapp_waba",
    "previousStatus": "in_progress",
    "currentStatus": "completed",
    "senderId": "snd_new123",
    "wabaAccountId": "waba_123456",
    "connectedAccount": {
      "channel": "whatsapp",
      "id": "109876543210",
      "name": "John Doe Store"
    }
  }
}

---

Sender Webhooks

Each sender can have one webhook configured. Webhooks are managed as part of the sender resource.

Via Dashboard

1. Go to Dashboard and select your project
2. Navigate to your Sender's settings
3. Click Add Webhook
4. Enter your webhook URL and select the events you want to receive
5. Save - you'll receive a signing secret

Via API

Configure a webhook when creating a new sender:

cURLCopy
curl -X POST https://api.zavu.dev/v1/senders \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Sender",
    "phoneNumber": "+15551234567",
    "webhookUrl": "https://your-app.com/webhooks/zavu",
    "webhookEvents": ["message.inbound", "message.delivered", "message.failed"]
  }'

Response:

JSONCopy
{
  "id": "snd_abc123",
  "name": "My Sender",
  "phoneNumber": "+15551234567",
  "isDefault": false,
  "webhook": {
    "url": "https://your-app.com/webhooks/zavu",
    "events": ["message.inbound", "message.delivered", "message.failed"],
    "secret": "whsec_abc123def456...",
    "active": true
  },
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Available Events

Inbound (Receiving Messages)

Outbound (Delivery Tracking)

Templates

Partner Invitations (Project Webhook)

Webhook Payload

All webhook payloads follow the same structure:

JSONCopy
{
  "id": "evt_1234567890_abc123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    // Event-specific data
  }
}

Handling Webhooks

Your webhook endpoint must:

1. Respond with 2xx status within 30 seconds
2. Verify the signature to ensure the request is from Zavu
3. Process asynchronously for long-running tasks

TypeScript (Express)Python (Flask)Ruby (Sinatra)GoPHPCopy
import express from "express";
const app = express();

app.post("/webhooks/zavu", express.json(), (req, res) => {
  // 1. Verify signature (see Security guide)
  const signature = req.headers["x-zavu-signature"];
  if (!verifySignature(signature, req.body, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  // 2. Acknowledge receipt immediately
  res.status(200).send("OK");

  // 3. Process the event asynchronously
  const event = req.body;
  processEvent(event).catch(console.error);
});

async function processEvent(event) {
  switch (event.type) {
    case "message.inbound":
      await handleInboundMessage(event.data);
      break;
    case "message.delivered":
      await handleDeliveryConfirmation(event.data);
      break;
    case "message.failed":
      await handleDeliveryFailure(event.data);
      break;
  }
}

Retry Policy

If your endpoint returns an error or doesn't respond within 30 seconds, Zavu will retry the delivery:

After 5 failed attempts, the webhook delivery is marked as failed. You can view failed deliveries in the Dashboard.

Managing Webhooks

Update Webhook Configuration

Update your sender's webhook settings:

cURLCopy
curl -X PATCH https://api.zavu.dev/v1/senders/snd_abc123 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://new-url.com/webhooks",
    "webhookEvents": ["message.inbound"],
    "webhookActive": true
  }'

Disable Webhook

cURLCopy
curl -X PATCH https://api.zavu.dev/v1/senders/snd_abc123 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookActive": false
  }'

Remove Webhook

Set webhookUrl to null to remove the webhook:

cURLCopy
curl -X PATCH https://api.zavu.dev/v1/senders/snd_abc123 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": null
  }'

Regenerate Secret

If your webhook secret is compromised:

cURLCopy
curl -X POST https://api.zavu.dev/v1/senders/snd_abc123/webhook/secret \
  -H "Authorization: Bearer zv_live_xxx"

Response:

JSONCopy
{
  "secret": "whsec_new_secret_here..."
}

Next Steps

• Event Types - Detailed payload for each event
• Security - Verify webhook signatures