Developers
SMS webhooks: get replies and opt-outs as they happen
Signilio SMS webhooks send a signed POST to your server when a lead replies, a conversation is assigned, or a contact opts out or back in. Set up in Settings.
A Signilio SMS webhook sends an HTTPS POST to your server when something happens in your texting: a lead replies, a conversation is assigned to a rep, or a contact unsubscribes or opts back in. Every delivery is signed with HMAC-SHA256, so your server can prove it came from Signilio before acting on it. It's the fastest way to keep your CRM, your data warehouse or your own app in step with every text conversation.
Two ways to set up webhooks
- In Settings (no code to start). The account owner adds a webhook with a name, an https address and the events to send: New incoming message, Conversation assigned to a rep, Contact unsubscribed and Contact re-subscribed.
- With an API key. Developers using the Signilio API can also receive message.delivered, message.failed and AI pause and resume events.
How to handle deliveries
- Answer fast. Return a 2xx right away and do the work afterwards.
- Verify the signature. Compute HMAC-SHA256 of the raw request body with your signing secret and compare it to the X-Signilio-Signature header.
- Expect retries and repeats. A failed delivery is retried 6 times over about 32 hours, so deliveries can arrive late, more than once and out of order. Deduplicate on the event name, its ids and its created_at time.
Events you can receive
New incoming message
A lead texted you. The payload includes the message, the conversation and the contact's number.
Conversation assigned
A conversation moved to a rep, so your CRM can update the owner too.
Contact unsubscribed
A contact opted out. Stop every other tool from contacting them.
Contact re-subscribed
A contact opted back in, or one rep was cleared to text them again.
Delivered and failed (API)
With an API key webhook, learn when each text was delivered or failed.
Signed and retried
Every delivery is signed, and a failed delivery is retried with backoff for about 32 hours.
How to add a webhook in Signilio
The account owner sets up Settings webhooks. Developers can also configure one on an API key.
- 1
Open webhooks
In Signilio, go to Settings → Integrations → Webhooks and click + Add Webhook.
- 2
Name it and add your address
Give it a name and the https address that should receive the POST.
- 3
Choose events
Pick the events to send: New incoming message, Conversation assigned to a rep, Contact unsubscribed, Contact re-subscribed.
- 4
Save the signing secret
The secret is shown once. Store it on your server to verify each delivery.
- 5
Send yourself a test
From your phone, text one of your Signilio numbers and check the delivery reaches your server.
Example
{
"event": "message.received",
"created_at": "2026-06-25T15:04:05.123Z",
"data": {
"message_id": "…",
"conversation_id": "…",
"contact_id": "…",
"from": "+13105551234",
"to": "+13105550000",
"body": "Is this still available?",
"received_at": "2026-06-25T15:04:05.000Z"
}
}const crypto = require("crypto");
app.post("/signilio/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("X-Signilio-Signature") || "";
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.SIGNILIO_WEBHOOK_SECRET)
.update(req.body) // the raw bytes, not re-serialized JSON
.digest("hex");
const ok = signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
res.sendStatus(200);
// handle the event after answering
});Good to know
- The signing secret is shown once. If you lose it, create the webhook again.
- Delivered and failed events are available on API key webhooks, not on webhooks added in Settings.
- Deliveries can repeat or arrive out of order. Deduplicate and order by created_at.
SMS webhook questions
- What is an SMS webhook?
- An SMS webhook is a message your texting platform sends to your server when something happens, such as an incoming text. Signilio sends it as a signed HTTPS POST with a JSON body.
- How do I receive incoming texts on my server?
- Add a webhook with your https address and the New incoming message event. Each reply arrives as a POST with the message and the contact's number.
- How do I know a webhook really came from Signilio?
- Check the X-Signilio-Signature header: it is an HMAC-SHA256 of the raw body using your signing secret. Reject any request where it doesn't match.
- What if my server is down?
- Signilio retries a failed delivery 6 times over about 32 hours. After a longer outage, read missed messages and conversations through the API.
- Can I get opt-out events?
- Yes. Contact unsubscribed tells you when a contact opts out, and Contact re-subscribed when they opt back in or one rep is cleared to text them again.