Richieste firmate
HMAC-SHA256 calcolato sul timestamp e sul corpo grezzo, inviato come X-Tailride-Signature: v1=…, con il timestamp in X-Tailride-Timestamp, così puoi rifiutare richieste vecchie o ripetute.
Webhook e API · Piani a pagamento
Ogni fattura elaborata, inviata ai tuoi sistemi.
Tailride invia un webhook JSON firmato nel momento in cui una fattura viene elaborata o modificata: fornitore, importi, IVA, righe della fattura e un link al PDF. Cerca le fatture tramite un’API REST, oppure collega Zapier e Make senza scrivere codice.
Che cos’è il webhook delle fatture di Tailride?
Un webhook è una richiesta HTTP POST che Tailride invia a un URL scelto da te. Gli eventi sono due: invoice.processed, quando una nuova fattura è stata letta, e invoice.updated, quando qualcuno la modifica, le allega un documento o la segna come pagata. Ogni richiesta è firmata con HMAC-SHA256, ritentata se il tuo server non è raggiungibile e annotata nel registro attività della fattura: così il tuo ERP, il tuo data warehouse o il tuo flusso di approvazione ricevono gli stessi dati che vedi nella dashboard.
Cosa riceve il tuo endpoint
La richiesta reale, header compresi
Ecco una consegna invoice.processed così come la invia Tailride. invoice.updated contiene la stessa fattura più l’elenco di ciò che è cambiato.
Sincronizzazione ERPhttps://erp.example.com/hooks/tailride
Attivo- Evento
- Fattura elaborata invoice.processed
- Secret di firma
- whsec_••••••••••••3f9aCopia secret di firmaRigenera secret di firma
- Header personalizzati
- Authorization: Bearer ••••••
import crypto from "node:crypto";
export function isFromTailride(req, rawBody, secret) {
const ts = req.headers["x-tailride-timestamp"];
const sig = req.headers["x-tailride-signature"]?.replace("v1=", "") ?? "";
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = crypto.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`).digest("hex");
return sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}curl "https://tailride.so/api/v1/invoices?search=northwind&limit=20" \
-H "X-Api-Key: trapi_…"POST /hooks/tailride HTTP/1.1
Content-Type: application/json
User-Agent: Tailride-Webhooks/1.0
X-Tailride-Event: invoice.processed
X-Tailride-Timestamp: 1792574400
X-Tailride-Signature: v1=5f2c8e…b41d
{
"event": "invoice.processed",
"timestamp": "2026-10-21T09:20:00.000Z",
"data": {
"invoice": {
"id": "6716f0c2e4b09a35d8f11a42",
"from": "billing@northwind.example",
"invoiceId": "INV-4471",
"invoiceDate": "2026-10-20T00:00:00.000Z",
"documentType": "invoice",
"amount": 1249,
"currency": "EUR",
"payment": { "status": "unpaid" },
"vendor": { "name": "Northwind Supplies GmbH", "countryCode": "DE", "taxId": "DE811234567" },
"items": [
{ "description": "Office chairs", "quantity": 2, "unitPrice": 524.79,
"taxRate": 19, "taxAmount": 199.42, "subtotal": 1049.58, "total": 1249 }
],
"tags": ["office"],
"attachment": { "url": "https://…/INV-4471.pdf", "expiresAt": "2026-10-22T09:20:00.000Z" }
}
}
}Come funziona
Cinque minuti nelle Impostazioni, poi ogni fattura arriva da sola.
01Aggiungi un endpoint
In Impostazioni → Webhook inserisci un nome e un URL, scegli l’evento e, se vuoi, aggiungi fino a cinque header personalizzati, ad esempio una chiave API che il tuo endpoint si aspetta.
02Copia il secret di firma
Ogni webhook ha il proprio secret whsec_. Usalo per verificare l’header X-Tailride-Signature. Puoi rigenerarlo quando serve: quello vecchio smette subito di funzionare.
03Ricevi le fatture
Quando una fattura viene elaborata o modificata, Tailride invia in POST un JSON con la fattura completa. Rispondi con un qualsiasi stato 2xx entro 10 secondi.
04Automatizza il resto
Scrivi i dati nel tuo ERP, in un database o in un flusso di approvazione, oppure lascia che se ne occupino le app Tailride per Zapier e Make, senza codice.
Pronto per la produzione
Nuovi tentativi ragionevoli
Fino a tre tentativi con un timeout di 10 secondi. Errori di rete, timeout e risposte 408, 429 e 5xx vengono ritentati; le altre risposte 4xx valgono come rifiuto. Usa data.invoice.id per ignorare un doppione.
La fattura completa
Fornitore e partita IVA, numero e date della fattura, importo, valuta, stato del pagamento, dettagli dell’abbonamento, tag e ogni riga con la sua aliquota d’imposta, più i link per scaricare il PDF e i documenti giustificativi.
Modifiche, non solo nuove fatture
invoice.updated scatta quando la fattura viene modificata, quando si aggiungono o rimuovono documenti giustificativi e quando cambia lo stato del pagamento, con il valore precedente e quello attuale di ogni campo modificato.
Ben protetto
Gli indirizzi privati e interni sono bloccati, i reindirizzamenti non vengono mai seguiti, e il secret di firma e i valori degli header personalizzati sono conservati cifrati.
Visibile su ogni fattura
Ogni consegna, e ogni consegna non riuscita, compare nel registro attività della fattura, così vedi cosa è stato inviato, dove e quando.
Cosa ci costruiscono i team
- Inviare ogni fattura elaborata a un ERP o a uno strumento interno che non ha un’integrazione nativa con Tailride.
- Caricare i dati delle fatture e delle singole righe in un data warehouse per i report sulla spesa.
- Avviare un’approvazione in Slack o Microsoft Teams tramite Zapier o Make quando arriva una fattura sopra un certo importo.
- Aggiornare un CRM o uno strumento di gestione progetti appena una fattura viene segnata come pagata.
Domande frequenti
A quali eventi posso iscrivermi?
invoice.processed scatta quando un nuovo documento è stato letto e riconosciuto come fattura. invoice.updated scatta quando una fattura elaborata cambia in seguito: campi modificati, documenti giustificativi allegati o rimossi, un nuovo stato di pagamento. Ogni webhook è iscritto a un solo evento: per riceverli entrambi, aggiungi un secondo webhook.
Come verifico che una richiesta arrivi davvero da Tailride?
Calcola l’HMAC-SHA256 del valore di X-Tailride-Timestamp, seguito da un punto e dal corpo grezzo della richiesta, usando il secret whsec_ del webhook. Confronta il risultato esadecimale con il valore dopo v1= in X-Tailride-Signature e rifiuta le richieste il cui timestamp risale a più di qualche minuto prima.
Cosa succede se il mio endpoint non risponde?
Tailride ci prova fino a tre volte, a pochi secondi di distanza. Errori di rete, timeout e risposte 408, 429 o 5xx vengono ritentati; qualsiasi altro 4xx è trattato come un rifiuto. Se tutti i tentativi falliscono, l’errore compare nel registro attività della fattura: usa l’API per recuperare ciò che ti sei perso.
Cosa può fare l’API REST?
Con una chiave API trapi_ puoi leggere i dati dell’account (GET /api/v1/me), cercare e sfogliare le fatture elaborate, fino a 100 per pagina, con GET /api/v1/invoices, e iscrivere Zapier o Make agli eventi delle fatture. L’URL di base è https://tailride.so/api/v1; invia la chiave come X-Api-Key o come token Bearer.
Esiste un’app per Zapier o Make?
Sì. L’app per Zapier è pubblica: trigger New Invoice e Updated Invoice e la ricerca Find Invoice. L’app per Make (monitorare fatture nuove o aggiornate, cercare fatture, effettuare una chiamata API) è disponibile su invito: chiedi il link all’assistenza.
Quali piani includono webhook e API?
Tutti i piani a pagamento, per gli account aziendali. Il titolare dell’account li gestisce in Impostazioni → Webhook: fino a 10 webhook e 10 chiavi API, più i webhook che Zapier e Make creano per te.
Per quanto tempo restano validi i link ai file?
I link di download in un webhook funzionano per 24 ore; quelli restituiti dall’API per un’ora. Se devi conservare il file, salvalo dalla tua parte.
Continua a leggere
Intorno a webhook e API
Le integrazioni pronte all’uso, la documentazione per sviluppatori e da dove arrivano le fatture in primo luogo.
Porta le tue fatture dove lavori davvero
Webhook, chiavi API e app per Zapier sono inclusi in ogni piano a pagamento.
