Webhooks
Ontvang realtime terugkoppelingen over updates in Smstools.
Wat zijn webhooks?
Webhooks zijn een uitbreiding van een API, maar in plaats van dat jouw code gegevens opvraagt van Smstools, stuurt Smstools gegevens naar jou. De gegevens komen aan in een webverzoek naar jouw toepassing. Webhooks worden ook gebruikt om jouw toepassing op de hoogte te stellen van gebeurtenissen zoals een inkomend gesprek of bericht. Omdat de servers van Smstools gegevens naar jouw toepassing moeten kunnen sturen via webhooks, moet je een webserver opzetten om de inkomende HTTP-verzoeken te ontvangen. Je moet ook de URL van elke webhook op jouw webserver specificeren, zodat gegevens naar elk kunnen worden verzonden.
| Type | Omschrijving |
|---|---|
| delivery_report | Rapportage na elk verzonden bericht. Soms kunnen er 2 webhooks zijn: eerst een 'ingediende' status en later een 'afgeleverde' of 'niet afgeleverde' status. Soms zijn er aanvullende details beschikbaar wanneer het bericht niet is afgeleverd. |
| read_report | Leesbevestiging nadat het bericht is gelezen. Een leesbevestiging is alleen beschikbaar voor Sociale Berichten of door gebruik te maken van de link 'Vraag om een leesrapport'. |
| inbox_message | Inkomend bericht. Alleen beschikbaar als je Sociale Berichten of een virtueel nummer gebruikt. |
| call_forwarding | Oproepdoorschakeling. Enkel beschikbaar als je Social Messaging of een virtueel nummer gebruikt. |
| add_contact | 1 contact werd toegevoegd via de API of software |
| delete_contact | 1 contact werd verwijderd via de API of software |
| add_group | Een groep werd toegevoegd via de API of software |
| delete_group | Een groep werd verwijderd via de API of software |
| add_optout | Een contact werd toegevoegd aan de opt-outlijst via de API of software |
| delete_optout | Een contact werd verwijderd uit de opt-outlijst via de API of software |
| funds_purchased | Het account heeft een nieuwe aankoop van tegoed voltooid |
| insufficient_funds | Het account heeft geen beschikbaar tegoed meer |
| email2sms_received | Email2Sms heeft een e-mail ontvangen en geprobeerd deze via SMS te verzenden |
| Codes voor detailrapportage bezorging | Status | Uitleg |
|---|---|---|
| 0 | SUBMITTED | Dit bericht is afgeleverd bij de operator maar we hebben geen bezorgrapport ontvangen. |
| 1 | DELIVERED | Dit bericht is succesvol afgeleverd. |
| 2 | NOT DELIVERED | Dit bericht is niet afgeleverd. Mogelijke reden: ontvanger bevindt zich buiten het bereik van het netwerk, netwerkproblemen, ontvanger in buitenland. |
| 3 | BUFFERED | Dit bericht is afgeleverd bij de operator maar niet bij de ontvanger. |
| 4 | REJECTED | Dit bericht is geweigerd door de operator. |
| 5 | REJECTED | Uitgebreide informatie hieronder! |
| 9 | UNKNOWN | Er zijn geen bezorgrapporten beschikbaar voor dit bericht. |
| Status | Uitleg |
|---|---|
| 10 | Ontvangersnummer is ongeldig of onbekend |
| 11 | Ontvanger bevindt zich tijdelijk buiten het bereik van de netwerkoperator |
| 12 | Probleem met de telefoon. |
| 13 | Probleem met het netwerk van de operator |
| 14 | Bericht verlopen - reden onbekend |
| 15 | Ontvanger staat op een zwarte lijst |
| 16 | Probleem met de inhoud van het bericht |
| 17 | Ontvanger kan niet worden afgehandeld |
| 18 | Operator heeft dit geweigerd vanwege spam |
| 19 | Abonnee kan geen premiumberichten ontvangen (geblokkeerd door operator) |
| Status | Uitleg |
|---|---|
| 2000 | INSUFFICIENT_FUNDS |
| 2001 | TOO_LONG |
| 2002 | TOO_SHORT |
| 2003 | TIMEOUT |
| 2004 | GATEWAY_ISSUES |
| 2005 | INVALID_SENDER |
| 2006 | INVALID_NUMBER |
| 4000 | UNKNOWN |
| 4001 | EMPTY_MESSAGE |
| 4002 | EMPTY_CLIENT |
| 4003 | LOCKED |
| 4004 | BLOCKED |
| 4005 | JOB_FAILED |
| 4006 | DUPLICATE |
| 4007 | INVALID_CONTENT |
Voorbeeld: bezorgrapport
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delivery_report",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
"datetime": "2019-01-01 00:00:00",
"datetime_utc": "2019-01-01 00:00:00",
"content": "here comes your message body",
"sender": "yoursender",
"receiver": "32470123456",
"reference": "yourref",
"delivery_code": "1",
"delivery_status": "delivered",
"delivery_status_datetime": "2019-01-01 00:00:00",
"delivery_code_detail": "10",
"delivery_code_detail_description": "Unknown Subscriber"
}
}
]
Voorbeeld: inkomend bericht
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "inbox_message",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"date_utc": "2019-01-01 00:00:00",
"sender": "sendernumber",
"receiver": "12345678",
"content": "message content",
"type": "sms",
"file": null,
"processed": 0
},
"isreply": {
"reply": true,
"orig_message_content": "original message content",
"orig_messageid": "985zvqipp73csuuha2079fbshx",
"orig_messagedate": "2019-01-01 00:00:00",
"orig_messagedate_utc": "2019-01-01 00:00:00",
"orig_sender": "32471123456",
"orig_receiver": "12345678",
"orig_reference": ""
}
}
]
Voorbeeld: oproepdoorschakeling
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "call_forwarding",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"date_utc": "2019-01-01 00:00:00",
"sender": "sendernumber",
"receiver": "12345678",
"content": "Incoming VOIP Call - Forwarded to XXXXX",
"content_type": "complete",
"type": "call"
}
}
]
Voorbeeld: leesbevestigingsrapport
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "read_report",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
"datetime": "2019-01-01 00:00:00",
"datetime_utc": "2019-01-01 00:00:00",
"content": "here comes your message body",
"sender": "yoursender",
"receiver": "32470123456",
"reference": "yourref",
"delivery_code": "1",
"delivery_status": "delivered",
"delivery_status_datetime": "2019-01-01 00:00:00",
"read_status": "message_read",
"read_datetime": "2019-01-01 00:01:00"
}
}
]
Voorbeeld: Contact toevoegen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_contact",
"username": "myusername",
"timezone": "Europe/Brussels",
"contact": {
"action": "add",
"groupid": "12345",
"groupname": "Groupname",
"receiver": "32498123456",
"firstname": "John",
"lastname": "Doe",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"unsubscribed": null,
"unsubscribe_date": null
}
}
]
Voorbeeld: Contact verwijderen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_contact",
"username": "myusername",
"timezone": "Europe/Brussels",
"contact": {
"action": "delete",
"groupid": "12345",
"groupname": "Groupname",
"receiver": "32498123456",
"firstname": "John",
"lastname": "Doe",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"unsubscribed": null,
"unsubscribe_date": null
}
}
]
Voorbeeld: Groep toevoegen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_group",
"username": "myusername",
"timezone": "Europe/Brussels",
"group": {
"action": "add",
"groupid": "12345",
"groupname": "Groupname"
}
}
]
Voorbeeld: Groep verwijderen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_group",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"content": "Group deleted",
"type": "group"
}
}
]
Voorbeeld: Opt-out toevoegen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_optout",
"username": "myusername",
"timezone": "Europe/Brussels",
"optout": {
"action": "add",
"id": "1234",
"number": "32498123456",
"memo": "Sample opt-out",
"date": "2025-08-04",
"date_utc": "2025-08-04"
}
}
]
Voorbeeld: Opt-out verwijderen
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_optout",
"username": "myusername",
"timezone": "Europe/Brussels",
"optout": {
"action": "delete",
"number": "32498123456",
"date": "2025-08-04",
"date_utc": "2025-08-04"
}
}
]
Voorbeeld: Tegoed aangekocht
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "funds_purchased",
"username": "myusername",
"timezone": "Europe/Brussels",
"funds": {
"order_id": "1234",
"item_amount": 1,
"currency": "eur",
"total_price": 10,
"price_excl": 0,
"purchase_type": "credits",
"payment_mode": "online",
"reference": "Reference",
"date": "2025-08-04 14:33:45",
"date_utc": "2025-08-04 12:33:45"
}
}
]
Voorbeeld: Onvoldoende tegoed
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "insufficient_funds",
"username": "myusername",
"timezone": "Europe/Brussels",
"funds": {
"item_amount": "0.000",
"item_type": "balance",
"message": "Insufficient funds",
"date": "2025-08-04 14:34:22",
"date_utc": "2025-08-04 12:34:22"
}
}
]
Voorbeeld: Email2SMS-trigger
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "email2sms_received",
"username": "myusername",
"timezone": "Europe/Brussels",
"email2sms": {
"sender": "[email protected]",
"receiver": {
"group": false,
"receiver": "32498123456"
},
"result": "Success",
"status": "Message Sent",
"email_message_id": "abc123def456",
"sms_message_id": "985zvqipp73csuuha2079fbshx",
"date": "2025-01-01 00:00:00",
"date_utc": "2025-01-01 00:00:00"
}
}
]