I webhook in uscita

Un webhook ti avvisa in tempo reale quando succede qualcosa in Accordyx — un contratto creato, firmato, una scadenza in arrivo — inviando un POST JSON firmato al tuo endpoint, invece di doverlo interrogare ripetutamente con l'API.

Creare un webhook

1. Nel tab Webhook, premi Nuovo webhook.
2. Inserisci l'URL del tuo endpoint: deve essere https e pubblicamente raggiungibile (indirizzi locali o privati vengono rifiutati). Non sono accettati nemmeno URL con nome utente o password incorporati, indirizzi IP non pubblici o scritti in forme insolite, e indirizzi IPv6 scritti come numeri: usa il nome di dominio del tuo endpoint.
3. Spunta gli eventi a cui vuoi iscriverti: «Contratto creato», «Contratto firmato», «Stato contratto cambiato», «Scadenza in arrivo», «Controparte creata», «Controparte aggiornata», «Approvazione conclusa», «Firma completata». Nessun evento è selezionato di default: scegli solo quelli che ti servono, così il tuo endpoint riceve solo i dati necessari.
4. Premi Crea webhook e, nel dialog Webhook creato, copia subito il secret mostrato: ti serve per verificare le firme e non sarà più visibile dopo la chiusura del dialog.

Verificare la firma

Ogni consegna include l'header X-Accordyx-Signature: t=<timestamp>,v1=<firma>. La firma è un HMAC-SHA256 calcolato col tuo secret sulla stringa timestamp + "." + corpo della richiesta; scarta le richieste con timestamp più vecchio di 5 minuti per proteggerti da eventuali replay.

Gestire i webhook attivi

Per ogni endpoint iscritto puoi:

• Premere Test per inviare subito un evento di prova e verificare che il tuo endpoint risponda correttamente. Se va bene leggi "Test riuscito: l'endpoint ha risposto" seguito dal codice HTTP, per esempio 200.
• Usare lo switch per sospendere o riattivare temporaneamente le consegne.
• Eliminarlo dal cestino: l'endpoint smette di ricevere eventi e l'operazione non è reversibile.

Il registro delle consegne

In fondo alla pagina trovi le ultime 50 consegne, con tipo di evento, esito ("in coda", "consegnato", "fallito", "abbandonato"), numero di tentativi ed eventuale codice HTTP di errore. Premi Aggiorna per rinfrescare.

Limiti

Puoi avere fino a 20 webhook attivi per organizzazione. Ogni consegna fallita viene ritentata fino a 10 volte con un'attesa crescente tra un tentativo e l'altro; dopo l'ultimo tentativo fallito lo stato passa ad "abbandonato". Se il tuo endpoint risponde con HTTP 410, Accordyx interpreta che non vuoi più ricevere eventi e disattiva la sottoscrizione in automatico.

Accordyx non segue i reindirizzamenti: se il tuo endpoint risponde con un codice 3xx (per esempio perché l'indirizzo è cambiato), la consegna conta come fallita. L'indirizzo di un webhook non si modifica: elimina il webhook e creane uno nuovo con l'indirizzo definitivo.

Problemi comuni

• "Inserisci l'URL https dell'endpoint" / "Seleziona almeno un evento" — completa entrambi i campi prima di creare il webhook.
• "URL non valido: serve un endpoint https pubblico" — l'indirizzo non rispetta le regole descritte sopra: usa un indirizzo https con il nome di dominio pubblico del tuo endpoint.
• "Limite di 20 webhook attivi raggiunto" — elimina i webhook che non usi più.
• Le consegne risultano «fallito» anche se l'endpoint funziona — controlla che l'endpoint risponda con un codice 2xx e non con un reindirizzamento 3xx.
• "Test fallito (HTTP ): " — il tuo endpoint non ha risposto correttamente: controlla che sia raggiungibile e che accetti richieste POST.