# Webhooks

Webhooks allow you to receive real-time updates about SMS delivery statuses and other events by automatically sending data to a specified URL whenever an event occurs.

During the onboarding process, please provide us with the webhook URL you'd like to use for receiving delivery reports.

# Authorization

To ensure webhook requests are secure and come from us, each request will include an X-Signature header.

You can verify this signature using your Webhook Secret and the raw payload of the request.

import crypto from "crypto"

export function verifyWebhookSignature(receivedSignature, secret, payload) {
    const expectedSignature = crypto
        .createHmac("sha256", secret)
        .update(payload)
        .digest("hex")

    const receivedBuffer = Buffer.from(receivedSignature)
    const expectedBuffer = Buffer.from(expectedSignature)

    // Ensure both Buffers have the same length
    if (receivedBuffer.length !== expectedBuffer.length) {
        return false
    }

    // Perform constant-time comparison
    return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

<?php

function verifyWebhookSignature($receivedSignature, $secret, $payload) {
    // Generate the expected signature using HMAC-SHA256
    $expectedSignature = hash_hmac("sha256", $payload, $secret);

    // Use hash_equals for constant-time comparison
    return hash_equals($expectedSignature, $receivedSignature);
}

# Request

A webhook request is sent as a JSON object and contains the following body:

Paramater	Description
`id`	The unique identifier of the message, generated after a successful call to one of the send method.
`status`	The status of the message; you can find the full list below.
`timestamp`	The delivery report date from the SMSC (Short Message Service Center).
`network`	The GSM network of the recipient's MSISDN (mobile number). Examples: 22601 = Vodafone, 22610 = Orange, 22603 / 22604 / 22606 = Telekom, 22605 = Digi Mobil. You can find the complete list here.

# Message status

The following statuses are available:

Status	Description
`new`	The message was received but has not yet been processed for sending to the operator.
`delivered_network`	The message was sent and received by the network operator. The operator has not yet confirmed whether the SMS was delivered to the customer.
`delivered`	The SMS was successfully delivered to the customer.
`temporary_error`	For example, if the recipient's phone is turned off, the system will attempt to resend the message. If a validity period was set when scheduling the message, no further attempts will be made after it expires. If no validity period is specified, the message will be retried based on the recipient's or mobile operator's retry algorithm.
`rejected`	The message was rejected by the operator. The number entered is incorrect (not configured by the operators) or no longer exists (it has been deactivated).
`permanent_error`	The recipient's phone is either turned off, experiencing issues, or out of network coverage, preventing the message from being marked as a temporary error. The message was not delivered within the maximum retry period set by each operator (up to 4 calendar days).
`smsc_carrier_rejection`	This status is rarely encountered and usually occurs when certain number ranges are reassigned to a different mobile network or are removed from use entirely.
`ported_number`	The message was not delivered because the number has been ported. We will update the network associated with the phone number and automatically resend the message.
`wrong_number`	The requested phone number is not valid.