🔔 What are webhooks and what they do for SMS and WhatsApp

A webhook is an automatic notification one system sends to another when something happens. Instead of your system asking every minute "did a message arrive?", the provider tells you the moment it does.

API versus webhook

With an API, your system takes the initiative: it asks to send an SMS, checks a status, originates a call. With a webhook, the provider takes the initiative: it tells your system that something happened.

The alternative to webhooks is asking over and over (known as polling). It works, but it wastes resources, arrives late and runs into usage limits. Webhooks solve all three.

How it works, step by step

1. You give the provider an HTTPS address on your system and the events you care about.
2. When one of those events happens, the provider sends a request to that address with the event data.
3. Your system verifies the signature, processes the event and quickly responds "received".

Examples with SMS, WhatsApp and calls

• Inbound message: a customer replies to an SMS or WhatsApp and your system receives it instantly to display it or act on it.
• Delivery status: the message you sent became delivered, read or failed; your system updates the order or retries on another channel.
• Queued call: a call comes in and your CRM opens the customer record before the agent answers.
• Missed call: someone hung up while waiting and your system creates a callback task.

Security: how to know the notification is genuine

Anyone who knows the address could send you fake data. That is why a serious webhook is signed:

• The provider computes a signature (usually HMAC with SHA-256) using a secret only you and the provider know, and sends it in a header.
• The signature includes a timestamp, so old notifications replayed by an attacker can be rejected.
• Your system recomputes the signature with the same secret and discards any notification that does not match.

The address should also be HTTPS, and the provider should not accept internal or private addresses.

Best practices for receiving webhooks

• Respond fast. Store the event and process it separately; if you take too long, the provider may treat it as failed.
• Use the event ID so you never process the same notification twice.
• Do not rely on order. A "delivered" can arrive before a "sent".
• Log failures and check the provider's delivery log when something does not add up.
• Protect the secret like a password and rotate it if it is exposed.

When you need webhooks

If your system only sends notifications and does not care what happens next, an API is enough. As soon as you need to react (to a customer reply, a failed message, an incoming call), you need webhooks.

The TelHarbor API includes signed webhooks for inbound messages, delivery statuses and call events, set up by our team. See also how to send SMS via API.