Un webhook invia un messaggio a un suo indirizzo ogni volta che succede qualcosa nella sua area di lavoro, per esempio quando un ordine viene pagato o un abbonamento viene annullato. Lo usi per mantenere sincronizzato un altro sistema, come uno strumento quale Zapier, la sua contabilità o il suo server.
Apra le impostazioni dei webhook
Prima di iniziare
La pagina si trova in Pagamenti > Impostazioni > Webhook, nel gruppo Sviluppatori. Per vederla serve Visualizza pagamenti. Per aggiungere, modificare, testare ed eliminare endpoint serve Aggiorna ordini / clienti.
Aggiungere un endpoint
Clicchi sul pulsante di aggiunta per aprire Aggiungi endpoint webhook:
- In Endpoint, gli dia un Nome facoltativo e inserisca l'URL dell'endpoint. L'indirizzo deve essere raggiungibile da internet. Gli indirizzi di una rete privata vengono rifiutati.
- In Eventi, scelga che cosa deve ricevere l'endpoint. Cerca eventi restringe l'elenco, la casella di un gruppo seleziona l'intero gruppo, e Seleziona tutto o Cancella tutto cambia tutto in una volta. Serve almeno un evento.
- Clicchi su Crea.
Gli eventi sono raggruppati per argomento:
- Pagamenti: Ordine pagato, Pagamento in corso, Pagamento non riuscito, Fattura pagata, Rimborso creato.
- Abbonamenti: Abbonamento creato, Abbonamento rinnovato, Abbonamento annullato, Pagamento dell'abbonamento non riuscito.
- Membri: registrazioni, accessi, tag aggiunti o rimossi, campi del membro modificati e nuovi contatti.
- Corsi ed eventi, Comunità e Dati e posta in arrivo: corsi e lezioni completati, iscrizioni e partecipazioni agli eventi, post, livelli, badge, messaggi della posta in arrivo e ticket.
- Affiliato: nuove commissioni e pagamenti effettuati, veda la guida sugli affiliati.
Il segreto di firma
Subito dopo la creazione dell'endpoint, l'area di lavoro mostra il suo segreto di firma una sola volta: Copi subito il suo segreto di firma. Lo conservi dalla sua parte, poi clicchi su Fatto. Non viene mostrato di nuovo.
Ogni consegna viene inviata come JSON con l'intestazione X-Maio-Signature. Contiene un
HMAC-SHA256 del corpo grezzo della richiesta, calcolato con il suo segreto, come stringa
esadecimale minuscola. Calcoli lo stesso valore dalla sua parte e lo confronti, così sa che il
messaggio proviene dalla sua area di lavoro. Le intestazioni X-Maio-Event e
X-Maio-Delivery indicano l'evento e la consegna.
Per sostituire il segreto, apra l'endpoint e clicchi su Ruota il secret. Il vecchio segreto smette subito di funzionare, quindi aggiorni immediatamente il suo endpoint.
Test
Apra l'endpoint e clicchi su Invia test. Il pulsante diventa Test in coda, e un evento di test arriva al suo endpoint entro pochi istanti. Compare nel registro di consegna come qualsiasi altra consegna.
Il registro di consegna
La scheda Registro di consegna elenca ogni consegna con Evento, Endpoint, Stato, lo stato HTTP con cui ha risposto il suo endpoint, i Tentativi e Quando. La filtri per Consegnato, Non riuscito o In sospeso. La sezione Consegne di un endpoint mostra le sue 20 consegne più recenti, con l'errore di ciascuna non riuscita.
Una consegna è considerata riuscita quando il suo endpoint risponde con uno stato 2xx entro 15 secondi. Altrimenti viene ritentata dopo 30 secondi, 5 minuti, 30 minuti, 2 ore e 6 ore. Invia di nuovo invia di nuovo una consegna con lo stesso contenuto.
Dopo 20 tentativi falliti di seguito per un evento, quell'evento viene disattivato per l'endpoint. Se l'endpoint risponde con 410 Gone, l'evento viene disattivato subito. Corregga l'endpoint, poi lo riporti su Attivo.
Disattivare ed eliminare
Nell'endpoint, l'interruttore passa tra Attivo e Disattivato. Un endpoint disattivato non riceve nulla. Elimina lo rimuove con tutti i suoi eventi dopo la sua conferma.
Dall'API
Le app collegate tramite l'API possono configurare i propri endpoint con gli
endpoint /api/v1/hooks e una chiave API con lo scope webhooks:manage.
Compaiono nell'elenco con un badge API, e qui si possono modificare solo il nome e lo stato.
Non hanno Ruota il secret né Invia test. Veda
Chiavi API e accesso per sviluppatori.