Webhooks

Webhooks allow you to receive real-time notifications when a transaction status changes. Configure an endpoint on your server to process these events automatically.

How it works

Transaction initiated

You initiate a collection via the API. The customer receives a validation prompt on their phone.

HMAC Signature

When the status changes, SebPay sends a POST to your callback_url with an HMAC-SHA256 signature in the header.

Confirmation

Your server verifies the signature and updates the order accordingly.

Webhook payload

When a transaction reaches a final status (approved or rejected), SebPay sends a JSON POST to the callback URL you specified.

POST

{your_callback_url}

Your endpoint must respond with an HTTP 200 status code to confirm receipt.

Headers

X-SebPay-SignatureRequired

string

HMAC-SHA256 signature of the JSON body, computed with the secret key of the transaction's environment (sk_live_... or sk_test_...).

Content-TypeRequired

string

application/json

Request Body

transaction_idRequired

string

Unique SebPay transaction identifier.

external_referenceRequired

string

Your external reference provided at creation.

statusRequired

string

Final status: approved, rejected or pending.

amountRequired

numeric

Transaction amount.

currencyRequired

string

Currency code (XOF, EUR, etc.).

customer_phoneRequired

string

Customer phone number.

created_atRequired

datetime

Transaction creation date.

updated_atRequired

datetime

Last update date.

Possible status values

approvedPayment was successfully confirmed by the customer.

rejectedPayment failed, was cancelled or expired.

pendingPayment is awaiting customer validation.

Signature verification

To ensure webhook authenticity, you must verify the HMAC-SHA256 signature sent in the X-SebPay-Signature header. Use your secret key to recompute the signature and compare.

# Test your own webhook endpoint locally with curl
# Replace https://yoursite.com/webhook/sebpay with your actual callback URL
curl -X POST https://yoursite.com/webhook/sebpay \
  -H "Content-Type: application/json" \
  -H "X-SebPay-Signature: your_computed_hmac_here" \
  -d '{
    "transaction_id": "20260505120000123456",
    "external_reference": "ORDER-789",
    "status": "approved",
    "amount": 5000,
    "currency": "XOF",
    "customer_phone": "22997000000",
    "created_at": "2026-05-05T12:00:00.000000Z",
    "updated_at": "2026-05-05T12:01:30.000000Z"
  }'

Best practices

Always verify the signature

Never process a webhook without verifying the HMAC signature. This protects your application from fraudulent requests.

Respond quickly (HTTP 200)

Your endpoint should respond with HTTP 200 within 5 seconds. If processing takes longer, store the event and handle it asynchronously.

Handle idempotency

The same webhook may be sent multiple times due to retries. Use the transaction_id to avoid processing the same event twice.