Webhooks salientes

Suscribite a eventos de facturas y compras y verificá cada entrega con la firma HMAC-SHA256.

En lugar de consultar las colas, Tario te avisa con un POST a tu URL cuando pasa algo. Gestionar suscripciones requiere la habilidad update.

Crear una suscripción

POST /api/v1/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{ "url": "https://tu-app.com/hooks/tario", "events": ["invoice.accepted", "bill.received"], "description": "ERP" }

La respuesta incluye data.secret una única vez: guardalo, las listas nunca lo vuelven a mostrar. GET /api/v1/webhooks lista las suscripciones (cada una con su last_delivery), PATCH /api/v1/webhooks/{id} con { "active": false } pausa o reactiva una, POST /api/v1/webhooks/{id}/test encola un ping firmado y DELETE /api/v1/webhooks/{id} elimina una. También podés administrarlas sin código en Configuración de la empresa → Integraciones → Webhooks.

Eventos

Evento	Cuándo
`invoice.accepted`	Hacienda aceptó una factura emitida
`invoice.rejected`	Hacienda rechazó una factura emitida
`bill.received`	Entró una factura de compra por XML (correo, manual o API)

Entrega

POST JSON a tu URL con los headers X-Tario-Event, X-Tario-Delivery (id de la entrega; se repite en cada reintento, usalo como clave de idempotencia) y X-Tario-Signature.
La firma es HMAC-SHA256(cuerpo_crudo, secret) en hexadecimal. Verificala sobre el cuerpo crudo, antes de parsearlo.
Si tu URL responde HTTP 400 o más (o tarda más de 10 s), Tario reintenta hasta 5 veces, con esperas de 1 min, 5 min, 30 min y 2 h. Cada intento actualiza la entrega (status, status_code, attempts, last_error), visible en Integraciones y en last_delivery.

{
  "event": "invoice.accepted",
  "occurred_at": "2026-06-12T10:00:00-06:00",
  "company_id": 42,
  "data": {
    "invoice_id": 1001,
    "invoice_number": "INV-1001",
    "document_type": "01",
    "document_key": "506...",
    "status": "accepted",
    "total_cents": 565000,
    "currency_code": "CRC"
  }
}

Verificar la firma (PHP)

$expected = hash_hmac('sha256', $request->getContent(), $secret);
abort_unless(hash_equals($expected, $request->header('X-Tario-Signature')), 401);