​
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. 
const crypto = require('crypto');

/**
 * Verify if the provided signature matches the computed signature for the data
 *
 * @param {string} data - The original data that was signed
 * @param {string} signature - The Base64 encoded signature to verify
 * @param {string} secretKey - The secret key used for signing
 * @returns {boolean} Returns true if signatures match, false otherwise
 */
function verifySignature(data, signature, secretKey) {
    try {
        // Create HMAC SHA512 hash
        const hmac = crypto.createHmac('sha512', secretKey);

        // Update with the data
        hmac.update(data);

        // Generate computed signature in base64
        const computedSignature = hmac.digest('base64');

        // Use crypto.timingSafeEqual to prevent timing attacks
        // First, convert both signatures to buffers
        const signatureBuffer = Buffer.from(signature);
        const computedSignatureBuffer = Buffer.from(computedSignature);

        // Compare signatures using constant-time comparison
        return signatureBuffer.length === computedSignatureBuffer.length &&
            crypto.timingSafeEqual(signatureBuffer, computedSignatureBuffer);

    } catch (error) {
        console.error('Error verifying signature:', error);
        return false;
    }
}

​
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.
EventDescription
airtime.successAirtime transaction was successfully completed
airtime.failedAirtime transaction attempted failed
airtime.duplicateIf you attempt to send the same airtime amount to the same recipient at the same interval
airtime.errorUnknown error
text.deliveredThe SMS message was successfully delivered
text.undeliveredThe SMS message failed to deliver
text.clickedThe link in the SMS was clicked
email.deliveredThe email was successfully delivered to the recipient
email.bouncedThe email failed to deliver
email.openedThe recipient opened the email
email.clickedThe recipient clicked a link in the email

​
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"
}