Webhooks

Two webhook channels

1) Stripe -> Clive

Endpoint:

• POST /api/v1/webhooks/stripe

Purpose:

• ingest Stripe payment lifecycle events
• update Clive transaction status and fee amounts

2) Clive -> Partner (Echezona)

Destination:

• your configured webhook_url on partner profile

Purpose:

• notify your system of transaction status updates after Stripe processing

Stripe event mapping used by Clive

Stripe event	Clive transaction status
payment_intent.succeeded	succeeded
payment_intent.payment_failed	failed
charge.refunded	refunded
charge.dispute.created	chargeback

Partner webhook payload (from Clive)

{
  "clive_tx_id": "CLVTX_1739378102312_420",
  "status": "succeeded",
  "amount": 750,
  "currency": "USD"
}

Partner webhook signature verification

Header:

• X-Clive-Signature

Signature algorithm:

• SHA-256 HMAC over exact JSON payload body
• secret: your partner webhook_secret

Delivery semantics

• Up to 3 delivery attempts
• Exponential backoff between retries
• success and failure outcomes are recorded in Clive audit events

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.