Webhooks

Overview#

Webhooks provide real-time notifications when significant state changes occur within the system. They enable external systems to react to updates without polling the API.

Event Flow#

1. Trigger: A webhook event is issued when a specific state change occurs.
2. Payload: The webhook is sent as a POST request to the configured endpoint with a JSON payload.
3. Acceptance: The receiving server must return an HTTP 2xx status to confirm successful processing.
4. Retry Mechanism: If a non-2xx response is received, retries follow an exponential backoff strategy.

Configuration#

Webhooks can be configured via the dashboard. You can set the endpoint URL, select the events to subscribe to, and manage security settings.

Webhook Structure#

Each webhook request follows a consistent structure to ensure idempotency and compatibility across API versions.

title: WebhookEvent
type: object
required:
  - id
  - api_version
  - type
  - data
properties:
  id:
    type: string
    example: "abcd1234"
    description: A unique identifier for the webhook event. Used for idempotency.
  api_version:
    type: string
    example: "1.0"
    description: The API version used for this webhook event.
  type:
    type: string
    enum:
    - account.low_balance
    - activation.updated
    - activation_report.updated
    - customer.low_balance
    - customer.updated
    - customer.activation.updated
    - customer.activation_report.updated
    - alternative.activation.updated
    example: activation.updated
    description: The type of webhook event.
  data:
    $ref: "#/components/schemas/EventData"

Idempotency#

The id field ensures that each event is uniquely identifiable. The receiver should ignore duplicate deliveries.

Webhook Acceptance and Response#

To confirm successful receipt of a webhook, the receiver must return an HTTP 2xx status. Failure to return a 2xx response will trigger the retry mechanism.

Delivery Retry Policy#

If the initial webhook delivery fails, retries occur with exponential backoff:

After the final attempt, the webhook is considered failed, and no further retries are made.

Authenticity Verification#

Each webhook request includes security headers for verification:

Signature Calculation#

To verify the authenticity of the webhook, compute the HMAC-SHA256 signature using the x-webhook-id, x-timestamp, and the request body. The signature is included in the x-signature header.

The signature is calculated as follows:

HMAC_SHA256(webhook_secret, x-timestamp + "\n" + request_body)

• Ensure x-timestamp is a string representing the UNIX timestamp.
• Use a newline (\n) separator between x-timestamp and request_body to avoid formatting issues.
• request_body must be the exact JSON payload as sent, encoded in UTF-8.