Skip to main content

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:

Create a Webhook

Register a webhook endpoint to start receiving events.
Response:

Configuration Options

The instance_id field is optional. If omitted, the webhook will receive events from all instances in your account.

List Webhooks

Response:

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 a secret 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

Always use constant-time comparison (like timingSafeEqual or hmac.compare_digest) when verifying signatures to prevent timing attacks.

Retry Behavior

If your server does not respond with a 2xx 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.
Response:

Event Payload Examples


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.