Webhooks

Webhooks notify you in real time about events on your sends. As soon as an event occurs, Conexteo sends an HTTP request to the URL you registered for that event type.

The three types

ack_sms: SMS delivery reports (delivered, failed).

reply: incoming replies from recipients, SMS and RCS (including clicks on RCS suggestions).

ack_rcs: RCS statuses (delivered, read, failed, SMS fallback). Available in signed mode only.

Signed or unsigned mode

Unsigned: simple delivery, with no delivery guarantee (see retries below).

Signed (recommended): every request carries an HMAC signature to verify, and benefits from retries. This mode is required for ack_rcs.

Verifying the signature

Every signed webhook is sent as a POST with three headers:

Header	Content
`X-Conexteo-Webhook-Id`	Unique event identifier (see Idempotency).
`X-Conexteo-Timestamp`	Send time, in seconds since January 1, 1970 (epoch).
`X-Conexteo-Signature`	`v1=` followed by the HMAC-SHA256 signature, in lowercase hexadecimal.

The signature is computed as follows:

HMAC_SHA256(secret, timestamp + "." + raw_body)

secret: your account's signing secret (starts with whsec_). It is shown only once, when your first signed webhook is enabled, and can be rotated via POST /webhooks/secret.

timestamp: the exact value of the X-Conexteo-Timestamp header.

raw_body: the request body exactly as received, before any JSON parsing. JSON that is parsed and then re-encoded will not produce the same signature.

To verify a webhook:

Reject the request if the timestamp differs from the current time by more than 5 minutes (replay protection).

Compute the expected signature using the formula above.

Compare it with the value received after v1=, using a constant-time comparison. If they differ, reject the request.

The v1= prefix allows the algorithm to evolve without breaking existing integrations.

Delivery and retries

Success or failure of an attempt
An HTTP 2xx response from your server = delivered. Any other status code, a timeout, or a network error = failed attempt.

Retries (signed webhooks only)
An unsigned webhook is sent only once: if it fails, it is not retried. A signed webhook is retried up to 8 attempts in total, with an increasing delay between each:

After failure no.	Next attempt in
1	30 seconds
2	2 minutes
3	10 minutes
4	30 minutes
5	1 hour
6	4 hours
7	12 hours

This gives a retry window of about 18 hours. After the 8th unsuccessful attempt, delivery is abandoned (status failed).

Idempotency
The X-Conexteo-Webhook-Id header stays identical across all attempts of the same event. Process each identifier only once: this is your protection against duplicates.

Monitoring
Check the status of your deliveries via GET /webhooks/deliveries (statuses: pending, delivered, failed, cancelled).

The three types#

Signed or unsigned mode#

Verifying the signature#

Delivery and retries#

The three types

Signed or unsigned mode

Verifying the signature

Delivery and retries