Webhooks
Webhooks let you receive real-time HTTP callbacks when events occur on your WhatsApp instances. Instead of polling the API, Wappfy pushes events to your server as they happen.Supported Events
Wappfy supports 12 webhook event types:Message Events
Message Events
Instance Events
Instance Events
Group & Contact Events
Group & Contact Events
Create a Webhook
Register a webhook endpoint to start receiving events.Configuration Options
The
instance_id field is optional. If omitted, the webhook will receive events from all instances in your account.List Webhooks
Update a Webhook
Update the URL, events, or configuration of an existing webhook.Delete a Webhook
Delivery Payload Format
When an event occurs, Wappfy sends a POST request to your webhook URL with the following structure:Payload Fields
HMAC Signature Verification
If you provide asecret when creating a webhook, every delivery will include an X-Wappfy-Signature header containing an HMAC-SHA256 signature of the request body.
Always verify this signature to ensure the request came from Wappfy and was not tampered with.
Verification Examples
Retry Behavior
If your server does not respond with a2xx status code within the configured timeout_ms, Wappfy will retry the delivery.
Retries stop when a
2xx response is received or the retry_count is exhausted. The default retry count is 3.Viewing Delivery History
Check the delivery log for a webhook to see past delivery attempts and their results.Event Payload Examples
message.received
message.received
message.delivered
message.delivered
message.read
message.read
message.reaction
message.reaction
instance.connected
instance.connected
instance.qr
instance.qr
group.joined
group.joined
Best Practices
Respond quickly
Return a
200 status within 5 seconds. Process the event asynchronously to avoid timeouts.Deduplicate
Use the delivery
id to detect and skip duplicate deliveries caused by retries.Verify signatures
Always validate the
X-Wappfy-Signature header if you configured a secret.Use HTTPS
Webhook URLs must use HTTPS. HTTP endpoints will be rejected.