Introduction

​

Why use webhook

When building Simpu integrations, you might want your applications to receive events as they occur, so that your backend systems can execute actions accordingly.

To enable webhook events, you need to register webhook endpoints. After registering them, Simpu can push real-time event data to your application’s webhook endpoint when specific events occur. Simpu uses HTTPS to send webhook events to your app as a JSON payload, which includes detailed information about the event. Receiving webhook events is particularly useful for tracking actions.

​

Event Overview

Simpu generates event data that can be sent to you to inform you of activities in your account.

When an event occurs, Simpu creates a new Event object. A single action might trigger multiple events.

By registering webhook endpoints in your Simpu account, you allow Simpu to automatically send Event objects via POST requests to your application’s registered webhook endpoint. Once your webhook endpoint receives the Event, your app can execute backend actions.

Webhooks allows you to listen to real-time events happening across your Simpu workspace. With webhooks, you can build custom integrations with simpu.

​

Verifying Events

It’s crucial to verify signatures of incoming webhook events to ensure they are genuine and haven’t been tampered with. This verification process helps protect your application from processing fraudulent events. For security purposes, each webhook event comes with a signature in the x-simpu-webhook-signature header. This signature is created using the following process:

The event payload is signed using HMAC-SHA512 algorithm The result is encoded in Base64 format This encoded signature is sent in the header

To verify an event:

Take the raw event payload (as a string) Take the signature from the x-simpu-webhook-signature header Use your secret key to compute a new signature Compare the computed signature with the received signature

Here’s a quick example of the verification flow:

// Get the signature from headers
const signature = request.headers['x-simpu-webhook-signature'];

// Get the raw payload
const payload = JSON.stringify(request.body);

// Verify the signature
const isValid = verifySignature(payload, signature, secretKey);

if (!isValid) {
    // Reject the webhook
    return response.status(401).send('Invalid signature');
}

// Process the webhook
// ... your processing logic here

Only process webhook events after successful signature verification. This ensures that your application only responds to genuine events from the authorized source.

​

Responding to an event

To handle Simpu webhooks, your application should respond with a 200 OK status to acknowledge the receipt of the event. If the response is anything other than 200, 201, or 202, the event will be considered unacknowledged, and Simpu will retry sending it every hour for up to 24 hours. Only the status code is required—any other parameters or request bodies will be ignored.

If your application needs to execute long-running tasks after receiving an event, it should still respond with a 200 OK immediately, before proceeding with the task, to avoid duplicate events being triggered.

​

Types of events

Here are the events we currently support. More will be added to this list as we integrate additional actions in the future.

​

Example

{
  "data": {
    "object": {
      "callback": "https://webhook.site/70652a3f-c84f-4efe-a63d-f272e66abc29",
      "amount": "12.0",
      "object": "airtime",
      "organisation_id": "897436867c0911eb8e5d9a88eb4ca9b7",
      "created_datetime": "2024-09-23T20:19:59.873639",
      "network": "GLO",
      "recipient": "2349055019322",
      "status": "success"
    }
  },
  "id": "evt.airtime_ExTefBPVsc1F901NXSNm1EZnvzpfOTcQ",
  "object": "event",
  "type": "AIRTIME_SUCCESS",
  "timestamp": "Sep 23, 2024, 8:20:01 PM"
}