Webhooks let you receive real-time HTTP notifications whenever an event happens in your Simiz account — payments, refunds, and more.

​
Why webhooks?

  • Real-time — Notifications delivered within seconds
  • Reliable — Automatic retries if your server is temporarily unavailable
  • Secure — HMAC SHA-256 signature on every request
Always use webhooks as the source of truth for payment status. Don’t rely solely on API polling or redirect callbacks.

​
How it works

​
Webhook payload structure

Every webhook event has the same envelope format: 
{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created_at": "2024-03-15T10:30:00Z",
  "data": {
    "id": "pay_xyz789",
    "object": "payment",
    "amount": 25000,
    "currency": "XOF",
    "status": "succeeded"
  }
}
FieldTypeDescription
idstringUnique event identifier
typestringEvent type (e.g., payment.succeeded)
created_atstringISO 8601 timestamp
dataobjectThe event payload (varies by event type)

​
Configuring webhooks

  1. Go to Dashboard → Settings → Webhooks
  2. Click Add Endpoint
  3. Enter your endpoint URL (must be HTTPS in production)
  4. Select which events to subscribe to
  5. Save — your webhook secret is displayed once
Copy your webhook secret immediately — it is only shown once. You’ll need it to verify webhook signatures.

​
Retry behavior

If your endpoint doesn’t return a 2xx response, Simiz retries the delivery automatically with increasing delays. After several failed attempts, the webhook is marked as failed. You can manually retry from the Dashboard.
Your endpoint should respond quickly — return 200 OK as soon as possible and process the event asynchronously if needed.

​
Best practices

  1. Always verify signatures — See the Signature Verification page
  2. Respond quickly — Return 200 OK before processing
  3. Handle duplicates — Use the event id for idempotent processing
  4. Use HTTPS — Webhook URLs must use HTTPS in production
  5. Log everything — Store raw payloads for debugging

Event Catalog

Browse all available webhook events.

Signature Verification

Learn how to verify webhook signatures.