Outgoing webhooks

Subscribe to invoice and purchase events and verify every delivery with the HMAC-SHA256 signature.

Instead of polling the queues, Tario notifies you with a POST to your URL when something happens. Managing subscriptions requires the update ability.

Create a subscription

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

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

The response includes data.secret only once: store it, lists never show it again. GET /api/v1/webhooks lists subscriptions (each with its last_delivery), PATCH /api/v1/webhooks/{id} with { "active": false } pauses or resumes one, POST /api/v1/webhooks/{id}/test queues a signed ping and DELETE /api/v1/webhooks/{id} removes one. You can also manage them without code under Company settings → Integrations → Webhooks.

Events

Event	When
`invoice.accepted`	Hacienda accepted an issued invoice
`invoice.rejected`	Hacienda rejected an issued invoice
`bill.received`	A purchase invoice arrived as XML (e-mail, manual, or API)

Delivery

JSON POST to your URL with the X-Tario-Event, X-Tario-Delivery (delivery id; the same on every retry, use it as an idempotency key) and X-Tario-Signature headers.
The signature is HMAC-SHA256(raw_body, secret) in hex. Verify it against the raw body, before parsing.
If your URL answers HTTP 400 or above (or takes longer than 10 s), Tario retries up to 5 times, waiting 1 min, 5 min, 30 min, and 2 h. Every attempt updates the delivery (status, status_code, attempts, last_error), visible under Integrations and in 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"
  }
}

Verify the signature (PHP)

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