Skip to main content

Webhooks

Overview​

Clive sends outbound webhooks to your configured partner endpoint whenever a transaction status changes.

Partners can create multiple webhook endpoints and subscribe each one to different events.

Where to create and view webhook secrets​

In the admin app:

  • Go to Partners
  • Select the partner
  • Open the Webhooks section under the API key area
  • Create a webhook with:
    • name
    • url
    • secret
    • one or more tracked events

Clive stores webhook secrets encrypted at rest and shows the secret again immediately after creation so your team can copy it into your system.

Supported partner webhook events​

  • transaction_succeeded
  • transaction_failed
  • transaction_abandoned
  • transaction_refunded
  • transaction_chargeback

Each configured endpoint receives the same payload shape. Only the event and status values change.

Delivery channel​

Clive -> Partner​

Destination: your configured webhook endpoint URL.

Purpose:

  • notify your system of transaction status updates

Partner webhook payload (from Clive)​

{
  "event": "transaction_succeeded",
  "clive_tx_id": "CLVTX_1739378102312_420",
  "partner_id": "ECHEZONA001",
  "client_id": "AIRPEACE001",
  "echezona_reference": "EZ12345",
  "status": "succeeded",
  "amount": 750,
  "currency": "USD",
  "meta": {
    "order_id": "ORD-1001",
    "customer_segment": "vip"
  }
}

Passing meta during transaction creation​

You can attach an optional meta object when calling either:

  • POST /api/v1/transactions/initialize
  • POST /api/v1/transactions/checkout-intent

Example:

{
  "partner_id": "ECHEZONA001",
  "client_id": "AIRPEACE001",
  "amount": 750,
  "currency": "USD",
  "echezona_reference": "EZ12345",
  "meta": {
    "order_id": "ORD-1001",
    "cart_id": "CART-2002",
    "customer_tier": "gold"
  }
}

Clive stores this meta object with the transaction and includes it unchanged in outbound webhook deliveries later.

Partner webhook signature verification​

Header:

  • X-Clive-Signature

Signature algorithm:

  • SHA-256 HMAC over exact JSON payload body
  • secret: the webhook secret you set when creating that specific endpoint

Delivery semantics​

  • Up to 3 delivery attempts
  • Exponential backoff between retries
  • success and failure outcomes are recorded in Clive audit events
  • Clive only sends to endpoints subscribed to the matching event

Partner-side webhook best practices​

  • Return 200 quickly after signature verification + enqueue processing.
  • Use idempotent processing keyed by clive_tx_id.
  • Do not assume ordered delivery.
  • Record full payload and signature for incident troubleshooting.