Webhook Configuration

The Webhooks page (/webhooks) lets you configure HTTP endpoints that receive real-time notifications when events occur in your merchant network. Instead of polling the API for changes, webhooks push data to your systems as events happen.

Summary Cards

When you have at least one webhook, three summary cards appear at the top of the page:

Total Webhooks

Total number of webhook endpoints configured.

Active

Webhooks currently operating normally (shown in green).

Failing

Webhooks that have experienced recent delivery failures (shown in amber).

Webhook Cards

Each configured webhook is displayed as a card showing:

Element	Description
URL	The endpoint URL where events are sent
Status	Current status: ACTIVE, FAILING, or DISABLED
Events	The event types this webhook is subscribed to
Last Success	Timestamp of the most recent successful delivery
Last Failure	Timestamp of the most recent failed delivery (if any)
Failure Count	Number of consecutive failures
Actions	Test, View History, and Delete buttons

Creating a Webhook

1. Open the creation dialog. Click the Add Webhook button in the top-right corner.

2. Enter the endpoint URL. Provide the HTTPS URL where you want to receive webhook events. This should be a publicly accessible endpoint on your server that can accept POST requests.

   Example: https://your-server.com/webhooks/sabibooks

3. Test the endpoint (recommended). Click the Test Endpoint button to verify that your server is reachable and responding correctly. The test sends a lightweight HTTP request to the URL and reports:

   • Success: “Endpoint responded successfully (150ms)” — the URL is reachable and your server responded with a 2xx status code.
   • Failure: A description of what went wrong (e.g., connection refused, timeout, non-2xx status code).

4. Select events to subscribe to. Choose which events should trigger notifications to this webhook (see Available Events below). You must select at least one event. Subscribe only to the events your system needs to process to minimize unnecessary traffic.

5. Create. Click Create Webhook to save the configuration. A success message confirms creation.

Available Events

Event	Label	When It Fires
merchant.created	Merchant Created	A new merchant registers under your partner account
merchant.updated	Merchant Updated	A merchant updates their profile or settings
merchant.suspended	Merchant Suspended	A merchant account is suspended
sale.completed	Sale Completed	A merchant completes a sale transaction
sale.voided	Sale Voided	A sale transaction is voided or reversed
payment.received	Payment Received	A payment is received from a customer
subscription.changed	Subscription Changed	A merchant changes their subscription plan
subscription.expired	Subscription Expired	A merchant’s subscription expires

Tip

High-volume events like sale.completed can generate significant traffic for large merchant networks. Subscribe selectively to only the events your system needs.

Example Webhook Payload

When an event fires, SabiBooks sends a POST request to your endpoint with a JSON payload:

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "sale.completed",
  "created_at": "2026-02-20T14:30:00Z",
  "data": {
    "sale_id": "sale_f8e7d6c5-b4a3-2190-fedc-ba0987654321",
    "merchant_id": "mer_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "business_name": "Mama Chidi Provisions",
    "amount": 150000.00,
    "currency": "NGN",
    "payment_method": "pos_terminal",
    "customer_phone": "+2348012345678",
    "items_count": 5
  }
}

Each delivery includes a signature header for verification. See Webhook Best Practices for details on signature verification.

Testing an Existing Webhook

After a webhook has been created, you can send a test ping to verify it is still working:

1. Find the webhook card on the page.
2. Click the Test button.
3. The portal sends a test event to your endpoint.
4. A success or failure message appears confirming the result.

Test pings are useful for:

• Verifying connectivity after server changes or deployments.
• Debugging delivery issues.
• Confirming your endpoint is correctly processing events.

Viewing Delivery History

To see the history of event deliveries for a specific webhook:

1. Click the View History button on the webhook card.
2. A modal opens showing recent delivery attempts.

Each delivery entry shows:

Field	Description
Event Type	The type of event that was sent (e.g., sale.completed)
Status	Delivery result: SUCCESS, FAILED, or PENDING
HTTP Status	The HTTP response code returned by your server (e.g., 200, 500, timeout)
Latency	How long it took your server to respond (in milliseconds)
Error Message	Description of the failure (for failed deliveries only)
Timestamp	When the delivery attempt occurred

Retrying Failed Deliveries

If a delivery failed, you can retry it:

1. Open the delivery history for the webhook.
2. Find the failed delivery entry.
3. Click the Retry button.
4. The portal re-sends the event payload to your endpoint.
5. The delivery status updates based on the retry result.

Retries are useful when failures were caused by temporary issues (e.g., server maintenance, brief network outages).

Deleting a Webhook

1. Click the Delete button on the webhook card.
2. A confirmation dialog appears showing the webhook URL so you can verify you are deleting the correct one.
3. Click Confirm to delete the webhook.

Caution

Deletion is permanent. Once deleted, no further events will be sent to the endpoint. If you want to temporarily stop receiving events without deleting the configuration, contact support about disabling the webhook instead.

Webhook Statuses Explained

Status	Meaning	Action Needed
ACTIVE	Operating normally. Recent deliveries have succeeded.	No action needed.
FAILING	Recent deliveries have failed. The endpoint may be unreachable or returning errors.	Investigate your endpoint. Check server logs, verify the URL is correct, and use the Test button to diagnose.
DISABLED	Disabled either manually or after repeated failures.	Review and fix the underlying issue, then re-enable or recreate the webhook.

Best Practices

1. Use HTTPS endpoints. Always use HTTPS (not HTTP) for your webhook URLs to ensure event data is encrypted in transit.

2. Respond quickly. Your endpoint should return a 2xx response within a few seconds. Do any heavy processing asynchronously after acknowledging receipt.

3. Handle duplicates. In rare cases, the same event may be delivered more than once. Design your handler to be idempotent — processing the same event twice should produce the same result.

4. Verify webhook signatures. Each webhook delivery includes a signature header. Verify this signature using your webhook secret to ensure the request genuinely came from SabiBooks.

5. Subscribe selectively. Only subscribe to the events you actually need. High-volume events like sale.completed can generate significant traffic for large merchant networks.

6. Monitor the Failing count. If a webhook enters FAILING status, investigate promptly. Persistent failures may indicate infrastructure issues on your end.

7. Test after deployments. When you update your webhook handler code, use the Test button to verify the endpoint still works correctly.

8. Log webhook payloads. Store received webhook data for debugging and auditing purposes.

Webhook Troubleshooting

Problem	Possible Cause	Solution
Webhook status is FAILING	Endpoint is unreachable or returning errors	Use the Test button to diagnose. Check server logs, firewall rules, and URL accuracy.
Events not being received	Wrong events selected or webhook is disabled	Verify the event subscriptions on the webhook card. Check that the webhook status is ACTIVE.
Test endpoint fails	Endpoint requires authentication or has CORS issues	Ensure your endpoint accepts unauthenticated POST requests (use webhook signature verification instead).
Duplicate events received	Retry caused re-delivery	Design your handler to be idempotent using the event ID as a deduplication key.
Cannot create webhook	Insufficient permissions	Only users with the PARTNER_ADMIN role can manage webhooks. See Roles and Permissions.
High latency warnings	Server processing too slow	Return a 2xx response immediately and process the payload asynchronously.

Related Pages

API Keys Generate credentials for programmatic access to the Partner API.

Branding Configuration Customize the white-label appearance of the merchant app.

Partner Portal Overview Portal introduction, login, navigation, and roles.