Configure Webhooks

Set up webhooks to receive real-time notifications for messages, delivery status updates, and campaign events.

Webhooks are HTTP callbacks that SendSeven uses to push real-time events to your application. Instead of polling the REST API, your endpoint receives instant notifications when something important happens — a message arrives, a conversation ends, a contact is created, or delivery status changes. Each webhook request is HMAC-signed for security and automatically retried on failure with exponential backoff, ensuring no events are lost.

A SendSeven account with at least one connected channel

A public HTTPS endpoint that can receive HTTP POST requests

A valid SSL certificate (Let's Encrypt works great)

Basic understanding of REST APIs and JSON

SendSeven dashboard Webhooks page with the Add Endpoint button highlighted

Add Endpoint dialog with HTTPS URL field and event subscriptions in SendSeven

Events: Select which events to receive (16 available)

Authorization Header (optional): Custom auth header sent with every delivery

Via the API you can also configure: retry_strategy (exponential/linear/none), max_retries (default 8, max 15), and timeout_seconds (default 30, range 5–60)

Webhook Created Successfully popup displaying the secret key with a Copy button

Webhook detail page showing endpoint URL, subscribed events, delivery history, and health status in SendSeven

conversation.closed — Conversation closed

An event occurs (e.g., message received)

If no 200, we retry with exponential backoff

Event type string (e.g., message.received)

ISO 8601 timestamp when the event occurred

ID of the resource that triggered the event

Event-specific payload (varies by event type)

Every event that includes a contact object also carries a contact_methods[] array listing all of the contact's identifiers (primary first). The top-level phone and email fields are kept for backwards compatibility.

Quick-reply and list selections arrive as message_type "button". The caption is in "text" and a structured "meta.button" object carries the id/payload so you can route on the selection without parsing text.

Show example with button click (quick-reply / list)

Stable identifier of the button as defined when the message was sent.

Payload returned by the channel (matches the id for quick replies).

Human-readable caption the user saw and tapped.

The attachments array is only present when the message includes media. Each attachment includes a unique id, content_type, file_size, and two download URLs. Supported types: image, video, audio, document, sticker.

url — Stable API endpoint. Requires authentication (API key or session token). Never expires.

signed_url — Pre-signed GCS URL. No authentication required. Expires after 24 hours.

If the platform media download fails, the raw platform data is passed through with a "source": "platform" marker instead of the enriched fields. Non-file types (location, contacts, reactions) are not affected.

Outbound messages that include file attachments contain the same enriched attachment schema (id, url, signed_url, content_type, file_size) as inbound messages.

The error field is at the data level (not inside message.meta). The full conversation and contact objects are also included.

Status update events (delivered, read) use a simpler conversation object without bot_session_id or last_*_at timestamp fields. The contact_method object is not included.

Email conversation objects include additional fields: email_integration_id and email_thread_id for threading context.

contact.updated uses the same structure as contact.created. The event type field distinguishes between them.

Get the raw request body (before parsing JSON)

Compute HMAC-SHA256 using your webhook secret

Prepend sha256= and compare with the X-Webhook-Signature header

Use timing-safe comparison to prevent timing attacks

Your URL is publicly accessible (not localhost)

Your SSL certificate is valid (not self-signed)

There's no firewall blocking SendSeven's IPs

Wrong webhook secret (copy again from settings)

Store the event ID and check for duplicates before processing

Respond with 200 as quickly as possible (process async)

Automatically when creating a webhook via the dashboard

Automatically when creating a webhook via the API (POST /api/v1/webhook-endpoints)

Automatically when the webhook URL is updated

On-demand via the verify endpoint (POST /api/v1/webhook-endpoints/{id}/verify)

1. Create a webhook endpoint
2. Register the webhook in SendSeven
3. Select event types to receive
4. Handle webhook verification challenge
5. Verify webhook signature
6. Handle incoming events
7. Test with sample events