Webhooks

A webhook is a method for automatically transmitting data to your application via HTTP. Since webhooks are event-driven, they activate when specific events occur, such as message.received, message.status.updated, call.added, or ussd-pull.status.updated. They help automate processes within your application by responding to these events. For instance, in an e-commerce app, if you want customers to receive order status updates via SMS, you can set up a webhook for the message.received event. This webhook can respond to customers when their message contains a valid order ID. Such use cases are ideal for webhooks.

You can add webhook by going to Webhooks page from navigation menu. Just click on Add to add a new webhook.

Fields

URL

URL of the script where you want to receive the data from webhook. It will send a post request to this URL.

Secret

This is an optional field but recommend. This can be used to authenticate that the request is indeed coming from the webhook. It will add a header called Signature that will contain a signature the receiving app can use to verify if the payload hasn't been tampered with. You can verify the signature as shown below.

    $secret = "your_webhook_secret";
    $payload = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_SIGNATURE'] ?? '';
    
    $computedSignature = hash_hmac('sha256', $payload, $secret);
    
    if (hash_equals($computedSignature, $signature)) {
        // 
    } else {
        http_response_code(403);
        die('Forbidden');
    }

    use Illuminate\Support\Facades\Route;
    use Illuminate\Http\Request;
    
    Route::post('/webhook', function (Request $request) {
        $secret = env('WEBHOOK_SECRET');
        $signature = $request->header('Signature');
        $computedSignature = hash_hmac('sha256', $request->getContent(), $secret);
    
        if (hash_equals($computedSignature, $signature)) {
            return response()->json(null, 204);
        }
    });

Events

Select events you want to subscribe too. There are four options as shown below.

call.added: Triggers when a new call was added to call log on any of the SIMs connected to the account.
message.received: Triggers when a new message is received on any of the SIMs connected to the account.
message.status.updated: Triggers when a message status changes.
ussd-pull.status.updated: Triggers when a USSD pull status changes.

Payload

You will receive post request on your URL when your subscribed events are triggered. The example payload for each event is shown below.

{
    event: "message.status.updated",
    data: {
        "id": 1,
        "number": "+14156661234",
        "incoming": true,
        "started_at": "2023-10-01T12:00:00Z",
        "ended_at": "2023-10-01T12:05:00Z",
        "sim_id": 1,
        "duration": "00:05:00",
        "type": "Incoming"
    }
}

{
    event: "message.received",
    data: {
        "id": 1,
        "from": "+14156661234",
        "to": "+14256661234",
        "content": "Sample message",
        "type": "SMS",
        "messageable_type": "sim",
        "messageable_id": 1,
        "sent_at": "2023-10-01T12:00:00Z",
        "delivered_at": "2023-10-01T12:05:00Z"
    }
}

{
    event: "message.status.updated",
    data: {
        "id": 1,
        "from": "+14156661234",
        "to": "+14256661234",
        "content": "Sample message",
        "type": "SMS",
        "status": "Sent",
        "retries": 0,
        "response": {
            "result_code": -1,
            "error_code": -1,
        },
        "campaign_id": 1,
        "messageable_type": "sim",
        "messageable_id": 1,
        "sent_at": "2023-10-01T12:00:00Z",
        "delivered_at": "2023-10-01T12:05:00Z"
    }
}

{
    event: "ussd-pull.status.updated",
    data: {
        "id": 1,
        "from": "+14156661234",
        "code": "*123#",
        "status": "Completed",
        "response": "Response message",
        "campaign_id": 1,
        "sim_id": 1,
        "sent_at": "2023-10-01T12:00:00Z",
        "received_at": "2023-10-01T12:01:00Z"
    }
}

14 June 2025