Webhooks Overview

ChatYug forwards WhatsApp events to your HTTPS endpoint as JSON POST requests.

How it works

Meta sends WhatsApp events to ChatYug.
ChatYug processes and stores the event.
ChatYug POSTs a normalized JSON payload to your configured webhook URL.

Configuration

Webhook URLs are configured only in the ChatYug portal — there is no External API endpoint to register or rotate webhooks programmatically.

Webhook Settings (login required): https://chatyug.com/webhook-settings

For each WABA you can set:

Webhook URL — public HTTPS endpoint on your server
Secret key — optional, used for HMAC signature verification
Active flag — enable or pause delivery

URL requirements

Must use HTTPS (HTTP allowed only in test environments when explicitly enabled server-side)
Must not resolve to private, local, or internal hostnames
Must return HTTP 2xx to acknowledge receipt

Event types

eventType	When fired
`message`	Customer sends a message (text, media, interactive reply, flow submission, etc.)
`status`	Outbound message status changes (sent, delivered, read, failed)
`order`	Customer places a WhatsApp catalog cart order
`test`	Portal "Send test event" to validate your endpoint

Payload envelope

Every outbound webhook uses the same top-level structure. See Event Reference for per-type data shapes.

{
  "eventType": "message",
  "userId": 42,
  "wabaId": "100000000000002",
  "phoneNumberId": "100000000000001",
  "eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
  "occurredAt": "2026-07-13T07:00:00.000Z",
  "data": { }
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-Chatyug-Event-Id`	Same value as `eventId` in the body — use for idempotency
`X-Chatyug-Signature`	`sha256=<hex>` HMAC of raw body when secret is configured

Next: Signature Verification · Retry & Troubleshooting