Pedidos assinados
HMAC-SHA256 sobre o carimbo de data/hora e o corpo em bruto, enviado como X-Tailride-Signature: v1=…, com o carimbo de data/hora em X-Tailride-Timestamp para que possa rejeitar pedidos antigos ou repetidos.
Webhooks e API · Planos pagos
Cada fatura processada, enviada para os seus próprios sistemas.
O Tailride envia um webhook JSON assinado assim que uma fatura é processada ou editada — fornecedor, valores, IVA, linhas da fatura e uma ligação para o PDF. Pesquise faturas através de uma API REST ou ligue o Zapier e o Make sem escrever código.
O que é o webhook de faturas do Tailride?
Um webhook é um pedido HTTP POST que o Tailride envia para um URL à sua escolha. Há dois eventos: invoice.processed, quando uma nova fatura acabou de ser lida, e invoice.updated, quando alguém a edita, lhe anexa um documento ou a marca como paga. Cada pedido é assinado com HMAC-SHA256, repetido quando o seu servidor não está disponível e registado no histórico de atividade da fatura, para que o seu ERP, data warehouse ou fluxo de aprovação receba os mesmos dados que vê no painel.
O que o seu endpoint recebe
O pedido real, com cabeçalhos e tudo
Esta é uma entrega invoice.processed tal como o Tailride a envia. O invoice.updated leva a mesma fatura e ainda uma lista do que mudou.
Sincronização ERPhttps://erp.example.com/hooks/tailride
Ativo- Evento
- Fatura processada invoice.processed
- Segredo de assinatura
- whsec_••••••••••••3f9aCopiar segredo de assinaturaRegenerar segredo de assinatura
- Cabeçalhos personalizados
- 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" }
}
}
}Como funciona
Cinco minutos nas Definições e, a partir daí, cada fatura chega sozinha.
01Adicione um endpoint
Em Definições → Webhooks, introduza um nome e um URL, escolha o evento e, se quiser, adicione até cinco cabeçalhos personalizados — por exemplo, uma chave de API que o seu endpoint exija.
02Copie o segredo de assinatura
Cada webhook tem o seu próprio segredo whsec_. Use-o para verificar o cabeçalho X-Tailride-Signature. Regenere-o sempre que precisar; o anterior deixa de funcionar de imediato.
03Receba as faturas
Quando uma fatura é processada ou alterada, o Tailride envia um POST com um JSON da fatura completa. Responda com qualquer estado 2xx no prazo de 10 segundos.
04Automatize o resto
Escreva os dados no seu ERP, numa base de dados ou num fluxo de aprovação — ou deixe que as apps do Tailride para Zapier e Make o façam sem código.
Feito para produção
Novas tentativas sensatas
Até três tentativas, com um tempo limite de 10 segundos. Erros de rede, tempos limite e respostas 408, 429 e 5xx são repetidos; as outras respostas 4xx contam como rejeição. Use data.invoice.id para ignorar uma repetição.
A fatura completa
Fornecedor e número de IVA, número e datas da fatura, montante, moeda, estado de pagamento, dados da subscrição, etiquetas e cada linha com a respetiva taxa de imposto — e ainda ligações para transferir o PDF e os documentos de suporte.
Alterações, não só faturas novas
O invoice.updated é disparado em edições, quando se adicionam ou removem documentos de suporte e quando o estado de pagamento muda, com o valor anterior e o atual de cada campo alterado.
Bem protegido
Os endereços privados e internos são bloqueados, os redirecionamentos nunca são seguidos, e o segredo de assinatura e os valores dos cabeçalhos personalizados são guardados encriptados.
Visível em cada fatura
Cada entrega — e cada entrega falhada — aparece no histórico de atividade da fatura, para que veja o que foi enviado, para onde e quando.
O que as equipas constroem com isto
- Enviar cada fatura processada para um ERP ou uma ferramenta interna sem integração nativa com o Tailride.
- Carregar os dados das faturas e das linhas num data warehouse para relatórios de despesas.
- Iniciar uma aprovação no Slack ou no Microsoft Teams através do Zapier ou do Make quando chega uma fatura acima de um determinado valor.
- Atualizar um CRM ou uma ferramenta de projetos assim que uma fatura é marcada como paga.
Perguntas frequentes
A que eventos posso subscrever?
O invoice.processed é disparado quando um novo documento foi lido e reconhecido como fatura. O invoice.updated é disparado quando uma fatura processada muda depois disso: campos editados, documentos de suporte anexados ou removidos, um novo estado de pagamento. Cada webhook subscreve um único evento, por isso adicione um segundo webhook para receber os dois.
Como verifico que um pedido vem mesmo do Tailride?
Calcule o HMAC-SHA256 do valor de X-Tailride-Timestamp, um ponto e o corpo do pedido em bruto, usando o segredo whsec_ do webhook. Compare o resultado em hexadecimal com o valor a seguir a v1= em X-Tailride-Signature e rejeite os pedidos cujo carimbo de data/hora tenha mais de alguns minutos.
O que acontece se o meu endpoint estiver em baixo?
O Tailride tenta até três vezes, com alguns segundos de intervalo. Erros de rede, tempos limite e respostas 408, 429 ou 5xx são repetidos; qualquer outra resposta 4xx é tratada como rejeição. Se todas as tentativas falharem, a falha aparece no histórico de atividade da fatura — use a API para obter o que lhe tiver escapado.
O que faz a API REST?
Com uma chave de API trapi_ pode ler a conta (GET /api/v1/me), pesquisar e percorrer as faturas processadas — até 100 por página — com GET /api/v1/invoices, e inscrever o Zapier ou o Make em eventos de faturas. O URL base é https://tailride.so/api/v1; envie a chave como X-Api-Key ou como token Bearer.
Existe uma app para Zapier ou Make?
Sim. A app do Zapier é pública: acionadores New Invoice e Updated Invoice e uma pesquisa Find Invoice. A app do Make — acompanhar faturas novas ou atualizadas, pesquisar faturas, fazer uma chamada à API — está disponível por convite; peça a ligação ao suporte.
Que planos incluem webhooks e a API?
Todos os planos pagos, para contas empresariais. O titular da conta gere-os em Definições → Webhooks: até 10 webhooks e 10 chaves de API, além dos webhooks que o Zapier e o Make criam por si.
Durante quanto tempo são válidas as ligações dos ficheiros?
As ligações de transferência num webhook funcionam durante 24 horas; as devolvidas pela API funcionam durante uma hora. Guarde o ficheiro do seu lado se precisar de o manter.
Continue a ler
À volta dos webhooks e da API
As integrações prontas a usar, a documentação para programadores e, antes de mais, de onde vêm as faturas.
Envie as suas faturas para onde o trabalho acontece
Webhooks, chaves de API e a app do Zapier estão incluídos em todos os planos pagos.
