Webhooks

A webhook is a POST request that Compense sends to a URL you own every time a business event happens in your entity (organization): a credit was approved, a top-up was confirmed, a loan payment was applied, an appointment was scheduled, a PQRS (complaints and requests) was answered. Instead of querying the API every so often (polling), your system finds out within seconds, and only when there is something new.

Everything is managed through the API, with your key: you register your endpoints, choose the events, rotate the signing secret, send test events, review the delivery history and retry failed deliveries. You don’t need to log in to the dashboard.

How a delivery works #

1. A change happens in your entity (through the API, from the dashboard or from the affiliate’s app). The event is written in the same transaction as the change: there is never a webhook for something that wasn’t recorded.
2. Compense sends a POST to each of your active endpoints subscribed to that event, with the signed JSON body.
3. Your receiver verifies the signature over the raw body, deduplicates by X-Webhook-Id, responds 2xx in under 10 seconds and processes in the background.
4. If your receiver doesn’t respond 2xx (or doesn’t respond in time), Compense retries the same delivery with exponential backoff. If it runs out of retries, the delivery becomes abandoned and you can retry it manually.

sequenceDiagram
    autonumber
    participant M as Compense engine
    participant D as Webhook dispatcher
    participant R as Your receiver
    participant Q as Your queue / DB
    M->>D: Event (same transaction as the change)
    D->>R: POST /compense/webhooks (JSON body + X-Webhook-Signature)
    R->>R: HMAC-SHA256(secret, raw body) == signature?
    alt Invalid signature or timestamp outside the window
        R-->>D: 401
    else Valid signature
        R->>Q: X-Webhook-Id already processed? if not, enqueue
        R-->>D: 200 (in under 10 s)
    end
    opt Non-2xx response, timeout or network error
        Note over D: Retries: 30 s, 2 min, 8 min, 32 min, ~2 h
        D->>R: POST (same delivery, same X-Webhook-Id)
        Note over D: No success after max_retries → abandoned
    end

At-least-once delivery #

Compense guarantees that each event is delivered at least once, not exactly once. An automatic retry can arrive even if your first response was in fact processed (for example, if your 200 got lost on the network). That’s why your receiver must be idempotent:

• Store the X-Webhook-Id (the event_id) of every processed event and discard duplicates.
• Don’t assume ordering between events. Use occurred_at and the state carried in resource to decide, and when in doubt, fetch the resource from the API.

The payload envelope #

Namespaced events (credits.*, subsidies.*, monetary_allowance.*, affiliates.*, wallets.*, loans, health, administrative and pqrs.*) share the same envelope:

{
  "event": "credits.decision",
  "version": "1",
  "tenant_id": "horizonte",
  "occurred_at": "2026-10-27T15:20:00Z",
  "resource": { "…": "event-specific fields" }
}

The classic credit lifecycle events (general category: application.*, credit.*, compliance.*, installment.due_soon) predate the envelope and carry their fields at the top level of the body, without resource. The SDKs give you the full body in payload so you can read them. Details and examples in Event catalog.

Headers on every delivery #

How to verify them step by step, with and without the SDK, in Verify the signature.

Endpoint lifecycle #

An endpoint goes through four states. You control the first two; Compense sets the other two based on how your receiver responds.

stateDiagram-v2
    [*] --> active: create
    active --> paused: PATCH active=false
    paused --> active: PATCH active=true
    active --> failing: 10 or more deliveries in 24 h, less than half successful
    active --> disabled: repeated 410 Gone
    failing --> disabled: repeated 410 Gone
    disabled --> [*]: create another endpoint

What you need before you start #

• An API key with the webhooks:read scope (read) and webhooks:manage (create, edit, rotate, test and retry).
• A public HTTPS URL for your receiver. localhost, private IPs and internal domains are not accepted; to develop on your machine see Test your webhooks.
• A secure place for the signing secret (whsec_...): it’s shown only once.

In this section #