Skip to content

Webhooks Overview

Webhooks allow your application to receive real-time HTTP POST notifications from Abelo when events occur throughout a message lifecycle.

Your application can provide one or more webhook endpoints that Abelo calls automatically when an event occurs that matches the subscribed topics for that webhook configuration.

This allows your application to react immediately to message delivery and engagement events and maintain an up-to-date view of your messaging activity.

1. Webhook Events

Abelo sends webhook events for important message lifecycle and engagement events, including:

Event Description
message.sent The message has been accepted for delivery.
message.delivered The message has been successfully delivered to the recipient.
message.seen The recipient has viewed the message.
message.clicked The recipient has clicked a tracked link or CTA.
message.failed The message could not be delivered.
message.expired The message reached its configured TTL without being delivered.

2. Two Delivery Routing Models

Abelo supports two distinct ways to receive webhook notifications:

graph TD
    Dispatch["Messaging Event"]
    Dispatch --> PerMsg{"Is webhook_url set in send request?"}
    PerMsg -- "Yes (Per-Message Routing)" --> CustomURL["POST to ad-hoc/overriden webhook_url<br/><br/><small>Signed with API Key's webhook_signing_secret, retrieved when API key is generated.</small>"]
    PerMsg -- "No (Organization Broadcast Routing)" --> OrgSub["Look up Organization's Webhook Subscriptions<br/><br/><small>Signed with Webhook's signing_secret, retrieved when webhook is set up.</small>"]

  1. Per-Message Webhook URL (Recommended for Multi-Tenant / Dynamic Integrations / Dev & Testing):

    1. Provide a webhook_url directly in your POST /v1/messages/send payload.
    2. Takes strict precedence over organization-level subscriptions for that single message.
    3. Dispatched events are HMAC-signed with your API key's webhook_signing_secret.
    4. Abelo will dispatch calls for all the lifecycle events of this specific message.

  2. Organization-Level Subscriptions (Broadcast):

    1. Configure global webhook endpoints in the CMS under Settings > Developer > Webhooks or via the /v1/webhooks REST API.
    2. Dispatched events are HMAC-signed with the Webhook's unique signing_secret.
    3. Abelo will dispatch calls for any campaign message and their events matching the subscribed topics.

3. Webhook Delivery Lifecycle

sequenceDiagram
    autonumber
    participant Abelo as Abelo Outbound Dispatcher
    participant Server as Your Webhook Server
    Abelo->>Server: HTTP POST (X-Abelo-Signature: sha256=...)
    Note over Server: Verify HMAC-SHA256 Signature
    Server-->>Abelo: HTTP 2XX (Within 15 seconds)
  1. HTTP Headers: Every webhook delivery includes cryptographic headers:
    • X-Abelo-Signature: The HMAC-SHA256 signature (sha256=<hex_digest>).
    • X-Abelo-Timestamp: The Unix timestamp when the request was dispatched.
    • X-Abelo-Topic: The event topic string (e.g. message.delivered).
    • X-Abelo-Delivery-Id: Unique UUID for idempotency and deduplication.
    • X-Abelo-Retry-Attempt: The retry sequence count.
  2. Acknowledgment: Your server must respond with an HTTP 2xx status code within 15 seconds.
  3. Automatic Retries: If your server returns a non-2xx response or times out, Abelo retries delivery using exponential backoff for up to 3 days period.

4. Managing Webhook Subscriptions via API

You can manage organization-level webhooks using the following REST endpoints (requires webhooks:manage scope):

Method Endpoint Description
POST /v1/webhooks Create a new webhook subscription. Returns signing_secret once.
GET /v1/webhooks List all configured webhooks for your organization.
GET /v1/webhooks/{webhook_id} Retrieve details for a specific webhook.
PATCH /v1/webhooks/{webhook_id} Update webhook URL, subscribed topics, or active status.
DELETE /v1/webhooks/{webhook_id} Delete a webhook subscription.
POST /v1/webhooks/{webhook_id}/rotate-secret Rotate signing secret (invalidates old secret immediately).
POST /v1/webhooks/test Dispatch a test signed payload to verify your receiver endpoint.

5. Global Webhook Rules

  • Maximum Limit: An organization can have a maximum of 5 active webhooks simultaneously.
  • Topic Overlap Prevention: Two active webhooks cannot subscribe to the same event topic. If a topic is assigned to one active webhook, it cannot be assigned to another.
  • Inactive Webhooks: Inactive webhooks do not count toward the limit of 5 and are exempt from topic overlap validation until activated.