Zaptickdocs
Resource

Webhooks

Real-time events: message statuses, inbound conversations, campaign progress, workflow runs and flow submissions.

#Payload shape

Every event share the same envelope:

JSON
{
  "id": "evt_01J3xkx7...",
  "type": "message.delivered",
  "createdAt": "2026-04-21T08:12:43.120Z",
  "data": {
    "messageId": "msg_01J3...",
    "phone": "+919876543210",
    "deliveredAt": "2026-04-21T08:12:42.948Z"
  }
}

#Signature verification

Every outbound request includes an X-Zaptick-Signature header and an X-Zaptick-Timestamp. The SDK ships a helper so you never have to implement HMAC comparison yourself:

TypeScript
import { verifyWebhookSignature } from 'zaptick/webhooks';

export async function POST(req: Request) {
  const payload   = await req.text();
  const signature = req.headers.get('x-zaptick-signature')!;
  const timestamp = req.headers.get('x-zaptick-timestamp')!;

  const ok = verifyWebhookSignature({
    payload, signature, timestamp,
    secret: process.env.ZAPTICK_WEBHOOK_SECRET!,
    tolerance: 300, // seconds, defaults to 5 min
  });

  if (!ok) return new Response('invalid signature', { status: 401 });
  // ... handle event
}

#Retries and replays

Zaptick considers a webhook successful only on 2xx responses. On failure we retry with exponential backoff: after 30s, 2m, 10m, 1h, 6h and 24h, then give up. Every attempt — successful or not — shows up in the dashboard at /dashboard/deliveries, where you can replay any delivery on demand.

#Event catalog

EventDescription
message.sentFired when a message leaves our system en route to Meta.
message.deliveredMeta confirmed delivery to the handset.
message.readThe user opened the message.
message.failedDelivery failed permanently. `data.error` carries the reason.
conversation.incomingUser sent a new inbound message.
conversation.resolvedAn agent marked a conversation as resolved.
campaign.launchedA campaign was pushed into the send queue.
campaign.completedAll recipients processed (success + failures).
workflow.startedA workflow run entered its first step.
workflow.completedA workflow run finished.
flow.submittedA user submitted a WhatsApp Flow.

#Managing endpoints via API

Dashboard-only right now
CRUD for webhook endpoints over the public API is still shipping. Today, create and manage endpoints via /dashboard/webhooks. The SDK surface at zaptick.webhooks.* is live code but reserved for the imminent public CRUD endpoint.