Webhook in tempo reale — rapporti di consegna, risposte, posta in arrivo, opt-out e altro.

Cosa sono i webhooks?

I webhooks sono un'estensione di un'API, ma invece che il tuo codice richieda dati da Smstools, Smstools invia dati a te. I dati arrivano in una richiesta web alla tua applicazione. I webhooks sono anche utilizzati per notificare la tua applicazione di eventi come una chiamata in arrivo o un messaggio. Poiché i server di Smstools devono essere in grado di inviare dati alla tua applicazione tramite webhooks, è necessario configurare un server web per ricevere le richieste HTTP in arrivo. È anche necessario specificare l'URL di ogni webhook sul tuo server web in modo che i dati possano essere inviati a ciascuno.

REGISTRATI →
  • Consegna in tempo reale
  • Endpoint sicuro
POST POST → il tuo endpoint 
{  "webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",  "webhook_type": "delivery_report",  "username": "myusername",  "timezone": "Europe/Brussels",  "method": "POST",  "created": "2026-01-01 09:00:06",  "created_utc": "2026-01-01 08:00:06",  "message": {    "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",    "datetime": "2026-01-01 09:00:00",    "content": "here comes your message body",    "sender": "yoursender",    "receiver": "32470123456",    "reference": "yourref",    "message_type": "sms",    "delivery_code": "1",    "delivery_status": "delivered",    "delivery_status_datetime": "2026-01-01 09:00:05",    "cost": 1,    "cost_type": "credits"  }}
Payload di esempio
Supporto UE
Conforme GDPR
Server UE · 99,97% uptime
Push in tempo reale

Tipo Descrizione
delivery_report Rapporto di consegna dopo ogni messaggio inviato. A volte possono esserci 2 webhooks: prima uno stato 'inviato' e successivamente uno stato 'consegnato' o 'non consegnato'. A volte sono disponibili dettagli aggiuntivi quando il messaggio non viene consegnato.
read_report Conferma di lettura dopo che il messaggio è stato letto. Una conferma di lettura è disponibile solo per la Messaggistica Sociale o utilizzando il link 'Richiedi un rapporto di lettura'.
inbox_message Messaggio in arrivo. Disponibile solo se si utilizza la Messaggistica Sociale o un numero virtuale.
call_forwarding Inoltro di chiamata. Disponibile solo se utilizzi la Messaggistica Sociale o un numero virtuale.
add_contact 1 contatto è stato aggiunto tramite API o software
delete_contact 1 contatto è stato rimosso tramite API o software
add_group Un gruppo è stato aggiunto tramite API o software
delete_group Un gruppo è stato rimosso tramite API o software
add_optout Un contatto è stato aggiunto alla lista di opt-out tramite API o software
delete_optout Un contatto è stato rimosso dalla lista di opt-out tramite API o software
funds_purchased L'account ha completato un nuovo acquisto di crediti
insufficient_funds L'account non ha più crediti disponibili
email2sms_received Email2Sms ha ricevuto un'email e ha tentato di inviarla via SMS
api_error Una richiesta API non è riuscita. Contiene il messaggio di errore, il codice di errore e lo stato HTTP della richiesta non riuscita.

Code Stato Spiegazione
0 SUBMITTED Questo messaggio è stato consegnato con l'operatore ma non abbiamo ricevuto alcun rapporto di consegna.
1 DELIVERED Questo messaggio è stato consegnato correttamente.
2 NOT DELIVERED Questo messaggio non è stato consegnato. Possibile motivo: il destinatario è fuori dal raggio di rete, problemi di rete, destinatario in paese straniero.
3 BUFFERED Questo messaggio è stato consegnato con l'operatore ma non consegnato al destinatario.
4 REJECTED Questo messaggio è stato rifiutato dall'operatore.
5 REJECTED Informazioni estese di seguito!
9 UNKNOWN Non ci sono rapporti di consegna disponibili per questo messaggio.

Di seguito una panoramica dei possibili codici di errore che potreste ricevere.

Stato Spiegazione
10 Il numero del destinatario non è valido o sconosciuto
11 Il destinatario è temporaneamente fuori dal raggio dell'operatore di rete
12 Problema legato al telefono.
13 Problema di rete dell'operatore
14 Messaggio scaduto - motivo sconosciuto
15 Il destinatario è elencato in una lista nera
16 Problema di contenuto del messaggio
17 Il destinatario non può essere liquidato
18 L'operatore ha rifiutato questo a causa di spam
19 Il sottoscrittore non può ricevere messaggi premium (bloccato dall'operatore)

Stato Spiegazione
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

Se sull'URL del webhook è impostato un segreto di firma, ogni richiesta webhook contiene gli header X-Smstools-Timestamp (timestamp Unix) e X-Smstools-Signature (formato: t={timestamp},v1={signature}).

Per verificare la firma: concatena il timestamp, un punto (.) e il corpo JSON grezzo della richiesta, calcola l'HMAC SHA-256 di questa stringa con il tuo segreto di firma e confronta il risultato con il valore v1. Per i webhook GET viene firmata la query string invece del corpo JSON.

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Smstools-Timestamp: 1767254406
X-Smstools-Signature: t=1767254406,v1=20bb9bf973ab6471e64f88a73fa11926c882dba87234f6760b87b5cbb0bf5aaa

$signedPayload = $timestamp . "." . $rawBody;
$signature = hash_hmac("sha256", $signedPayload, $secret);
hash_equals($signature, $v1);

Esempio: rapporto di consegna

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:00:06",
	"created_utc": "2026-01-01 08:00:06",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Dettagli aggiuntivi in caso di messaggio NON CONSEGNATO (Code 2)

								{
	"webhook_id": "wh_b1c67831-8bed-4d89-b15e-73632e2e4c10",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:00:15",
	"created_utc": "2026-01-01 08:00:15",
	"message": {
	  "messageid": "f2rl90fycahg7gagvodfzn3te78i99",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "2",
	  "delivery_status": "not delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:12",
	  "delivery_code_detail": "10",
	  "delivery_code_detail_description": "Unknown Subscriber",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Campi aggiuntivi in caso di risposta o conferma di lettura

								{
	"webhook_id": "wh_c2d78942-9cfe-4e9a-8c26-84743f3f5d21",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:02:35",
	"created_utc": "2026-01-01 08:02:35",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "confirm_type": "replies_yes_no_answer",
	  "confirm_date": "2026-01-01 09:02:30",
	  "confirm_memo": "YES",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Esempio: rapporto di conferma di lettura

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "read_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:01:01",
	"created_utc": "2026-01-01 08:01:01",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "read_status": "message_read",
	  "read_datetime": "2026-01-01 09:01:00"
	}
}

Esempio: messaggio in arrivo

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "inbox_message",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:05:01",
	"created_utc": "2026-01-01 08:05:01",
	"message": {
	  "id": "12345678",
	  "public_id": "inb_46f4c0e37652d4149352e1cb54fed50b",
	  "date": "2026-01-01 09:05:00",
	  "date_iso8601": "2026-01-01T09:05:00+01:00",
	  "date_utc": "2026-01-01 08:05:00",
	  "date_utc_iso8601": "2026-01-01T08:05: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": "2026-01-01 09:00:00",
	  "orig_messagedate_iso8601": "2026-01-01T09:00:00+01:00",
	  "orig_messagedate_utc": "2026-01-01 08:00:00",
	  "orig_messagedate_utc_iso8601": "2026-01-01T08:00:00+00:00",
	  "orig_sender": "32471123456",
	  "orig_receiver": "12345678",
	  "orig_reference": ""
	}
}

Esempio: inoltro di chiamata

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "call_forwarding",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:10:01",
	"created_utc": "2026-01-01 08:10:01",
	"message": {
	  "id": "12345678",
	  "public_id": "inb_7ecad8b1a486b73732b897fde12f080c",
	  "date": "2026-01-01 09:10:00",
	  "date_iso8601": "2026-01-01T09:10:00+01:00",
	  "date_utc": "2026-01-01 08:10:00",
	  "date_utc_iso8601": "2026-01-01T08:10:00+00:00",
	  "sender": "sendernumber",
	  "receiver": "12345678",
	  "content": "Incoming VOIP Call - Forwarded to XXXXX",
	  "content_type": "complete",
	  "type": "call"
	}
}

Esempio: Aggiungi contatto

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_contact",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:15:00",
	"created_utc": "2026-01-01 08:15:00",
	"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": false,
	  "unsubscribe_date": null
	}
}

Esempio: Elimina contatto

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_contact",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:16:00",
	"created_utc": "2026-01-01 08:16:00",
	"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": false,
	  "unsubscribe_date": null
	}
}

Esempio: Aggiungi gruppo

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_group",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:20:00",
	"created_utc": "2026-01-01 08:20:00",
	"group": {
	  "action": "add",
	  "groupid": "12345",
	  "groupname": "Groupname"
	}
}

Esempio: Elimina gruppo

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_group",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:21:00",
	"created_utc": "2026-01-01 08:21:00",
	"group": {
	  "action": "delete",
	  "groupid": "12345",
	  "groupname": "Groupname"
	}
}

Esempio: Aggiungi opt-out

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_optout",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:30:00",
	"created_utc": "2025-08-04 12:30:00",
	"optout": {
	  "action": "add",
	  "id": "1234",
	  "number": "32498123456",
	  "memo": "Sample opt-out",
	  "date": "2025-08-04",
	  "date_utc": "2025-08-04"
	}
}

Esempio: Elimina opt-out

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_optout",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:31:00",
	"created_utc": "2025-08-04 12:31:00",
	"optout": {
	  "action": "delete",
	  "number": "32498123456",
	  "date": "2025-08-04",
	  "date_utc": "2025-08-04"
	}
}

Esempio: Crediti acquistati

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "funds_purchased",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:33:50",
	"created_utc": "2025-08-04 12:33:50",
	"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"
	}
}

Esempio: Crediti insufficienti

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "insufficient_funds",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:34:22",
	"created_utc": "2025-08-04 12:34:22",
	"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"
	}
}

Esempio: Trigger Email2SMS

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "email2sms_received",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-01-01 10:00:02",
	"created_utc": "2025-01-01 09:00:02",
	"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 10:00:00",
	  "date_utc": "2025-01-01 09:00:00"
	}
}

Esempio: errore API

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "api_error",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:25:00",
	"created_utc": "2026-01-01 08:25:00",
	"error": {
	  "error": "Destination number 32498123456 missing or invalid",
	  "error_code": 103,
	  "sender": "yoursender",
	  "receiver": "32498123456",
	  "http_code": 400,
	  "date": "2026-01-01 09:25:00",
	  "date_utc": "2026-01-01 08:25:00"
	}
}
Scopri la nostra piattaforma SMS oggi!

Inviare SMS non è mai stato così semplice.

REGISTRATI → Contatti