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 a webhook by going to the Webhooks page from the navigation menu. 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 recommended. 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 to. 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 a 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",
        "started_at": "2023-10-01T12:00: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"
    }
}

15 December 2025