Webhook
Un evento inviato con POST a un endpoint HTTPS: ricevute, messaggi in entrata e cambi di stato che il destinatario deve verificare, confermare rapidamente e mettere in coda.
Solo definizioni — un termine spiegato qui non è un servizio che vendiamo.
Un webhook è un callback HTTPS che invia con POST un evento a un URL registrato dal cliente, come una ricevuta di consegna o un messaggio in entrata. Il destinatario verifica la firma, conferma con un 2xx e mette in coda l’elaborazione.
Il destinatario gestisce duplicati ed eventi fuori ordine; un webhook è una consegna in modalità push.
Verificare, confermare, mettere in coda
Il provider invia un POST quando si verifica un evento e l’endpoint del cliente restituisce un 2xx per confermarlo. Il payload è di norma JSON con un tipo di evento e un identificativo. Il provider può firmarlo; la firma va verificata sul corpo grezzo con il segreto condiviso, e le richieste al di fuori della finestra di replay vanno respinte.
Prima verificare, poi salvare l’evento grezzo, restituire un 2xx ed elaborare in modo asincrono. Gli endpoint lenti provocano nuovi tentativi. La consegna è di norma at-least-once e l’ordine non viene preservato, quindi occorre deduplicare sull’ID dell’evento. Conviene mantenere una dead-letter queue per gli eventi che non possono essere elaborati. La guida SMPP e HTTP a confronto confronta i callback con la consegna basata su sessione.