How to configure webhooks with the smsmode© API

When using the smsmode© SMS API to send SMS messages, it is often useful to automatically receive replies from recipients (incoming SMS messages) or to be notified in real time of a message's delivery status (‘delivery confirmation’). This is where webhooks come in: they allow you to receive automated HTTP calls to an endpoint of your choice as soon as an SMS-related event occurs.

Typical events you may want to capture include:

• receipt of an incoming SMS (MO – ‘Mobile Originated’) to a number or alias you have configured;
• delivery status (DLR – ‘Delivery Receipt’) for a message sent via the API: delivered, failed, in progress;

possibly, clicks on a short link or unsubscription (‘STOP’) if you use additional features.
 

Why is this important?

• You can move towards a real conversation: when a customer replies to your SMS, you can take their reply into account (e.g. ‘Yes’, “STOP”, ‘1’).
• You improve service quality: by receiving statuses, you can detect delivery failures and resend or track.
• You automate your workflows: for example, trigger an alert in your CRM or ticketing tool when a ‘STOP’ response arrives.
• You ensure compliance and deliverability: knowing when an SMS is rejected or blocked helps you monitor your campaigns.
   

How do you set up a webhook?

a) Create/activate your endpoint

• On your server/application, define a secure public URL (HTTPS) capable of receiving POST requests.
• Ensure that it can process JSON (or another) format and respond quickly (often < 300 ms) to avoid timeouts.

b) Configure in smsmode© (or via the API)

• In your smsmode© space or via the corresponding API key, specify this URL as the ‘receiving webhook’ or ‘status callback’.
• Choose the events to activate (responses, statuses, etc.).
• Check that your URL is accessible from outside (no firewall blocking).

c) Best practices for processing

• Check the event to find out the type of notification.
• Save the data in your database (message_id, recipient, status, text) for traceability.
• Respond quickly with an HTTP 200 code if your process has successfully received the webhook, to prevent it from being sent again.
• Manage any retransmissions (e.g. a webhook sent twice).
• Secure your endpoint: authentication (token, authorised IPs, etc.).

 

4. Concrete use cases

• Automatic retry: If a message is returned as ‘failed’, trigger an internal alert or a new sending attempt.
• Automatic unsubscription: If the text received is ‘STOP’, mark the contact as unsubscribed and do not send any more marketing SMS messages.
• Real-time deliverability statistics: Record all ‘delivered’ vs. ‘undelivered’ statuses to trigger reports.

• Interactive conversation: When a customer replies ‘YES’, trigger a workflow (e.g. sending a link, assigning an advisor, etc.).

 

5. Checks & recommendations

 

• Check that you have sufficient API quota or credits before sending (to avoid ‘failed’ messages).
• If you use a sender ID (custom sender), check that it complies with legislation (France/EU).
  Ensure that your webhooks are highly available and that you handle errors (5xx returns, timeouts).
• Keep a history of events for audits (e.g. a recipient replied but was not taken into account).
• Be aware of delays: there may be a few seconds/minutes of latency in delivery or return.