Peticiones firmadas
HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar, enviado como X-Tailride-Signature: v1=…, con la marca de tiempo en X-Tailride-Timestamp para que puedas rechazar peticiones antiguas o repetidas.
Webhooks y API · Planes de pago
Cada factura procesada, directa a tus propios sistemas.
Tailride envía un webhook JSON firmado en cuanto se procesa o edita una factura: proveedor, importes, IVA, líneas y un enlace al PDF. Busca facturas con una API REST o conecta Zapier y Make sin escribir código.
¿Qué es el webhook de facturas de Tailride?
Un webhook es un HTTP POST que Tailride envía a la URL que elijas. Hay dos eventos: invoice.processed, cuando se ha leído una factura nueva, e invoice.updated, cuando alguien la edita, le adjunta un documento o la marca como pagada. Cada petición va firmada con HMAC-SHA256, se reintenta si tu servidor no está disponible y queda registrada en el historial de actividad de la factura, así que tu ERP, tu almacén de datos o tu flujo de aprobación reciben los mismos datos que ves en el panel.
Lo que recibe tu endpoint
La petición real, cabeceras incluidas
Así es una entrega invoice.processed tal como la envía Tailride. invoice.updated lleva la misma factura y además una lista de lo que ha cambiado.
Sincronización ERPhttps://erp.example.com/hooks/tailride
Activo- Evento
- Factura procesada invoice.processed
- Secreto de firma
- whsec_••••••••••••3f9aCopiar secreto de firmaRegenerar secreto de firma
- Cabeceras personalizadas
- 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" }
}
}
}Cómo funciona
Cinco minutos en Ajustes y, a partir de ahí, cada factura llega sola.
01Añade un endpoint
En Ajustes → Webhooks, introduce un nombre y una URL, elige el evento y, si quieres, añade hasta cinco cabeceras personalizadas; por ejemplo, una clave de API que espere tu endpoint.
02Copia el secreto de firma
Cada webhook tiene su propio secreto whsec_. Úsalo para comprobar la cabecera X-Tailride-Signature. Regenéralo cuando lo necesites; el anterior deja de funcionar al instante.
03Recibe facturas
Cuando una factura se procesa o cambia, Tailride hace un POST con un JSON que contiene la factura completa. Responde con cualquier estado 2xx en un plazo de 10 segundos.
04Automatiza el resto
Escribe los datos en tu ERP, en una base de datos o en un flujo de aprobación, o deja que las apps de Tailride para Zapier y Make lo hagan sin código.
Pensado para producción
Reintentos sensatos
Hasta tres intentos con un tiempo de espera de 10 segundos. Se reintentan los errores de red, los tiempos de espera agotados y las respuestas 408, 429 y 5xx; cualquier otra respuesta 4xx cuenta como rechazo. Usa data.invoice.id para ignorar una repetición.
La factura completa
Proveedor y NIF-IVA, número y fechas de la factura, importe, moneda, estado de pago, datos de suscripción, etiquetas y cada línea con su tipo de IVA, además de enlaces de descarga del PDF y de los documentos adjuntos.
Cambios, no solo facturas nuevas
invoice.updated se dispara con las ediciones, al añadir o quitar documentos adjuntos y con los cambios de estado de pago, e incluye el valor anterior y el actual de cada campo modificado.
Bien protegido
Las direcciones privadas e internas están bloqueadas, las redirecciones nunca se siguen, y el secreto de firma y los valores de las cabeceras personalizadas se guardan cifrados.
Visible en cada factura
Cada entrega, y cada entrega fallida, aparece en el historial de actividad de la factura, para que veas qué se envió, adónde y cuándo.
Lo que construyen los equipos con él
- Enviar cada factura procesada a un ERP o a una herramienta interna que no tenga integración nativa con Tailride.
- Cargar los datos de facturas y líneas en un almacén de datos para informes de gasto.
- Iniciar una aprobación en Slack o Microsoft Teams mediante Zapier o Make cuando llega una factura por encima de un importe fijado.
- Actualizar un CRM o una herramienta de proyectos en cuanto una factura se marca como pagada.
Preguntas frecuentes
¿A qué eventos me puedo suscribir?
invoice.processed se dispara cuando se ha leído un documento nuevo y se ha reconocido como factura. invoice.updated se dispara cuando una factura procesada cambia después: campos editados, documentos adjuntos añadidos o quitados, un nuevo estado de pago. Cada webhook se suscribe a un solo evento, así que añade un segundo webhook para recibir ambos.
¿Cómo compruebo que una petición viene de verdad de Tailride?
Calcula el HMAC-SHA256 del valor de X-Tailride-Timestamp, un punto y el cuerpo sin procesar de la petición, con el secreto whsec_ del webhook. Compara el resultado en hexadecimal con el valor que sigue a v1= en X-Tailride-Signature y rechaza las peticiones cuya marca de tiempo tenga más de unos minutos.
¿Qué pasa si mi endpoint está caído?
Tailride lo intenta hasta tres veces, con unos segundos de separación. Se reintentan los errores de red, los tiempos de espera agotados y las respuestas 408, 429 o 5xx; cualquier otra respuesta 4xx se trata como rechazo. Si fallan todos los intentos, el fallo aparece en el historial de actividad de la factura; usa la API para recuperar lo que te hayas perdido.
¿Qué puede hacer la API REST?
Con una clave de API trapi_ puedes leer la cuenta (GET /api/v1/me), buscar y paginar las facturas procesadas, hasta 100 por página, con GET /api/v1/invoices, y suscribir Zapier o Make a los eventos de facturas. La URL base es https://tailride.so/api/v1; envía la clave como X-Api-Key o como token Bearer.
¿Hay una app para Zapier o Make?
Sí. La app de Zapier es pública: disparadores New Invoice y Updated Invoice, y una búsqueda Find Invoice. La app de Make (vigilar facturas nuevas o actualizadas, buscar facturas, hacer una llamada a la API) está disponible por invitación; pide el enlace a soporte.
¿Qué planes incluyen los webhooks y la API?
Todos los planes de pago, para cuentas de empresa. El propietario de la cuenta los gestiona en Ajustes → Webhooks: hasta 10 webhooks y 10 claves de API, además de los webhooks que Zapier y Make crean por ti.
¿Cuánto tiempo son válidos los enlaces a los archivos?
Los enlaces de descarga de un webhook funcionan durante 24 horas; los que devuelve la API, durante una hora. Guarda el archivo en tu lado si necesitas conservarlo.
Sigue leyendo
En torno a los webhooks y la API
Las integraciones listas para usar, la documentación para desarrolladores y de dónde salen las facturas en primer lugar.
Lleva tus facturas adonde ocurre tu trabajo
Los webhooks, las claves de API y la app de Zapier están incluidos en todos los planes de pago.
