Vai al contenuto principale
L’integrazione Webhooks è pensata per gli sviluppatori. Invia un evento JSON a un indirizzo HTTPS che scegli tu ogni volta che succede qualcosa in Foliant, così il tuo sistema può reagire, ad esempio archiviando il PDF di ogni fattura o recuperando un’esportazione completata. Webhooks è in beta. Se non lo vedi in Impostazioni › Integrazioni, non è ancora disponibile per il tuo negozio. Contatta l’assistenza per chiedere l’accesso.

Eventi

Collega i webhook

  1. In Foliant, vai su Impostazioni › Integrazioni.
  2. Su Webhooks, fai clic su Collega.
  3. Compila le impostazioni:
  4. Fai clic su Collega.
Puoi modificare l’URL, il secret e gli eventi in seguito in Impostazioni nella pagina dell’integrazione.

Cosa contiene ogni richiesta

Foliant invia una richiesta POST con un corpo JSON:

Dati di document.generated

  • template: uuid e name del modello.
  • document_type: invoice, credit_note, quote oppure vuoto per gli altri documenti.
  • order: i suoi id, name e type (ordini o bozze di ordini).
  • refund_id e fulfillment_id, quando il documento riguarda un rimborso o una spedizione.
  • document_number e issued_at, per i documenti numerati.
  • source: come è stato creato, ad esempio download, admin_download, export o email.
  • export: l’ID dell’esportazione, quando fa parte di un’esportazione.
  • generated_at.

Dati di export.completed

  • export: i suoi uuid, order_type, template_uuids, il numero di orders, orders_skipped (eliminati dopo essere stati scelti) e documents, requested_by (merchant o customer) e completed_at.
  • download_url: un link per scaricare l’esportazione, e download_url_expires_at, quando quel link smette di funzionare.
  • download_expires_at: quando scade l’esportazione stessa.
Gli eventi contengono ID e conteggi, non indirizzi email dei clienti.

Verifica la firma

La firma è un HMAC-SHA256 esadecimale del timestamp, di un punto e del corpo grezzo della richiesta (<timestamp>.<body>), con il tuo signing secret come chiave. Calcolala dal tuo lato e confrontala con il valore dopo sha256= in X-Foliant-Signature. Usa il corpo grezzo esattamente come lo hai ricevuto.

Risposte e nuovi tentativi

  • Qualsiasi risposta 2xx vale come consegnata.
  • Se il tuo endpoint restituisce un errore 5xx, 408 o 429, oppure non risponde entro 10 secondi, Foliant riprova più tardi, aspettando ogni volta più a lungo, fino a 5 tentativi.
  • Le altre risposte 4xx sono definitive: Foliant non riprova.
  • Ogni evento viene consegnato una sola volta per documento o esportazione. I nuovi tentativi non lo inviano mai due volte dopo un successo.
Ogni invio compare in Attività nella pagina dell’integrazione, dove puoi fare clic su Riprova per quelli non riusciti. Vedi Attività dell’integrazione.

Articoli correlati