Don’t call us, we’ll call you! Voodoo SMS supports Webhooks so you don’t have to rely on polling us every second to get the data you require, instead, we will call the script you provide and give you a JSON payload object that you can then manipulate as you wish.


To begin, you can enable Webhooks and choose which events you want to use in Send SMS>API SMS>Webhooks.

By default, they will be disabled. You can enable them by choosing Enable from the drop-down menu.


The job of a secret is for you to validate your secret against the incoming requests’ header. We supply a X-Voodoo-Token header with each request that is encoded with base64. You can validate this by checking your secret matches up to the encoded request and if it does, then you know it’s valid, otherwise, it might mean some outside force is trying to get access.

Validating with secret is actually optional, it will still work if you don’t validate, but it’s recommended that you do validate.

See on the right how you can validate the secret against the token.

Validating Secrets Example (optional)

$header = getallheaders();

if ($header['X-Voodoo-Token'] === base64_encode('my_secret')) {
    echo "Header matches!";
} else {
    echo "Header doesn't match";


Events are things that happen on the portal and we can tell you that it happened and give you some data relating to what happened, meaning you can then do something with that data.

Just choose which event you want to listen for and enable it and supply your Webhook URL and when that event occurs, your script will be called and a JSON payload object will be sent to it, which you can catch and manipulate as you desire.


Below is an example of how to listen for these events been fired and the payload data that is sent across.

This example is for getting a Delivery Report - other events will have different data
Example script to listen for the payload data

$payload = file_get_contents('php://input');

$sms = json_decode($payload);

echo "Hi, it looks like $sms->sender_id has sent you a message";
Payload Data Example
    "message_id": "545661962492569139807064833622133327042010220",
    "sender_id": "VoodooSMS",
    "to": "447000999888",
    "sent_at": "2020-07-27 10:58:33",
    "delivered_at": "2020-07-27 10:58:38",
    "status": "DELIVERED",
    "external_reference": "Voodoo",
    "credits_used": "1.00"