Saltar al contingut principal
Els webhooks d’alertes envien les alertes del vostre equip a un endpoint HTTPS que vosaltres controleu. Feu-los servir per alimentar una eina de guàrdia, una cua de tiquets o el vostre propi tauler d’operacions. Els webhooks d’alertes són independents dels webhooks de verificació. Els webhooks de verificació envien els resultats de sessions, entitats i transaccions a la vostra aplicació. Els webhooks d’alertes avisen el vostre equip que alguna cosa necessita atenció: una verificació pendent de revisió, un pagament fallit o un incident de servei. Tenen el seu propi payload, secret de signatura, signatura i calendari de reintents.

Configura una destinació del webhook

Configureu els webhooks d’alertes a la Business Console, no mitjançant l’API. Els membres que poden gestionar la configuració de l’organització poden afegir, modificar i provar les destinacions.
1

Afegiu la destinació

A Configuració de l’organització > Notificacions de l’equip, afegeix una destinació de tipus Webhook d’alertes amb la URL del vostre endpoint. La URL ha de fer servir https:// i resoldre a una adreça pública.
2

Desa el secret de signatura

Didit mostra el secret de signatura complet, que comença per whsec_, només una vegada. Deseu-lo ara: després, la consola només mostra els darrers quatre caràcters.
3

Envieu-hi les alertes

Afegir una destinació no envia res encara. Afegiu la destinació a les regles d’enrutament de les alertes que vulgueu que rebi.
4

Envieu una prova

Feu clic a Envia una prova per enviar una alerta alert.test i comproveu que el vostre endpoint l’accepta.
Una organització pot tenir fins a 25 destinacions a Notificacions de l’equip. Només l’activitat en entorn de producció arriba a una destinació. Les alertes sobre verificacions de sandbox, verificacions d’empreses (KYB), transaccions i coincidències AML mai no s’hi envien.

Tipus d’alertes

Payload

Cada alerta és un POST amb un cos JSON. Didit envia el cos com a JSON compacte amb les claus ordenades. Aquest exemple està formatat per facilitar la lectura:
data sempre conté:
  • event: la clau de l’esdeveniment, per exemple session_in_review.
  • label i value: sobre què tracta l’alerta, per exemple Session i #1042.
Alguns tipus d’alerta afegeixen claus a data:
  • alert.billing.autorefill_failed afegeix paused, un booleà que és true quan la recàrrega automàtica queda pausada fins que actualitzeu la targeta.
  • alert.service.degraded i alert.service.recovered afegeixen service, status, incident_id, service_name, state, affected, country_name, started_at, resolved_at, duration_minutes, title i body. status és degraded o down a alert.service.degraded, i recovered a alert.service.recovered. service fa servir les claus de servei de GET /v3/status/, i incident_id coincideix amb un id d’incident d’aquell endpoint.
Les alertes mai no inclouen dades personals ni de documents de l’usuari final. Identifiquen una sessió, una transacció o un altre element pel seu número i hi enllacen des de la consola. Ignoreu els valors de webhook_type i les claus de data que no reconeixeu, perquè els nous no trenquin el vostre endpoint.

Capçaleres de la sol·licitud

Verifica la signatura

X-Signature-V2 és el HMAC-SHA256 en hexadecimal de la cadena <X-Timestamp>.<raw body>, amb el secret de signatura de la teva destinació.
  • Fes servir el secret complet exactament tal com el va mostrar Didit, incloent-hi el prefix whsec_.
  • Signa els bytes sense processar de la petició tal com els has rebut. Analitzar el JSON i tornar-lo a serialitzar pot canviar els bytes i trencar la verificació.
  • Compara les signatures en temps constant.
  • Rebutja una petició amb un X-Timestamp que difereixi més de 5 minuts del teu rellotge. Didit signa cada intent, inclosos tots els reintents, amb una marca de temps nova, de manera que aquesta finestra mai no rebutja un reintent genuí.
  • Respon amb 400 quan la verificació falli. Una resposta 401, 403, 404 o 410 marca la destinació perquè es torni a connectar (vegeu Reintents).
Els webhooks d’alertes no es signen igual que els webhooks de verificació. La capçalera també es diu X-Signature-V2, però la cadena signada és diferent, i els webhooks d’alertes no envien cap X-Signature ni X-Signature-Simple. No reutilitzis el verificador del webhook de verificació.

Node.js (Express)

Python (Flask)

Rota el secret de signatura

Rotes el secret de la destinació a Notificacions de l’equip. Didit mostra el secret nou una sola vegada i signa amb ell tots els intents posteriors, inclosos els reintents d’alertes creades abans de la rotació. El secret antic deixa de funcionar de seguida. No hi ha cap període de solapament, i cap capçalera no porta una signatura feta amb el secret anterior. Desplega el secret nou al teu endpoint tan bon punt el rotis.

Reintents

Didit considera lliurada qualsevol resposta 2xx. Cada intent espera fins a 5 segons la resposta i no segueix les redireccions. Didit reintenta una alerta després d’un temps d’espera, d’un error de connexió, d’una resposta 5xx, o d’una resposta 408, 425 o 429. Reintenta fins a 5 vegades, durant unes 24 hores: Qualsevol altra resposta és definitiva, incloses les 3xx i qualsevol altra 4xx. Una prova enviada amb Envia una prova té un únic intent i mai no es reintenta. Una resposta 401, 403, 404 o 410 també marca la destinació perquè es torni a connectar: la consola la mostra amb l’estat Tornar a connectar. També marca la destinació una URL que, quan Didit hi envia, es resol en una adreça privada o bloquejada. Didit continua enviant alertes noves a la destinació, i torna a estar activa després del següent lliurament satisfactori o quan actualitzes la seva URL. Notificacions recents dins de Notificacions de l’equip mostra cada lliurament amb el seu resultat, i des d’allà pots reintentar un lliurament fallit.

Relacionat

Darrera modificació el 7 de novembre del 2026