Webhooks
Event notification
BuildingIn development for the v1 API. The contract is set; the route is not served yet.
We POST every event to the URL you register. Verify the Heru-Signature header (HMAC-SHA256 of timestamp.body with your webhook secret) and reply 2xx within 10 seconds. We retry with backoff for 24 hours.
application/json- body
id*stringUnique per event. Use it to discard duplicates.
Match
^evt_[0-7][0-9a-hjkmnp-tv-z]{25}$type*stringValue in
"fiscal_validation.completed""fiscal_validation.failed""social_security_validation.completed""social_security_validation.failed""worker.updated""signature.completed""invoice.stamped""invoice.cancelled""retention_certificate.stamped""retention_certificate.cancelled""batch.done""merchant.activated""merchant.csd_expiring""charge.invoiced"created_at*stringFormat
date-timedata*The full resource, same shape as its GET.
Your reply
Answer any 2xx within 10 seconds; heru ignores the body. Any other status, or no answer in time, counts as a failed delivery and is retried with backoff for 24 hours.
Example events
Pick an event to see the request heru sends.
POST /v1/webhooks/compliance HTTP/1.1Host: api.acme-delivery.exampleContent-Type: application/jsonHeru-Event-Id: evt_01m4ra8x08eq7vth7a13qb5y8fHeru-Event-Type: fiscal_validation.completedHeru-Signature: t=1760281481,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd{ "id": "evt_01m4ra8x08eq7vth7a13qb5y8f", "type": "fiscal_validation.completed", "created_at": "2026-10-12T15:04:41.203Z", "data": { "id": "fv_01m4ra8vqve0xv4yfe92canf5a", "external_id": "FV-2026-004413", "status": "completed", "message": null, "pending": [], "result": { "curp": "HEGL900101HDFRRS06", "name": "JOSE LUIS HERNANDEZ GARCIA", "given_names": "JOSE LUIS", "first_surname": "HERNANDEZ", "second_surname": "GARCIA", "rfc": "HEGL900101K44", "rfc_valid": true, "rfc_active": true, "postal_code": "06600", "regimes": [ { "code": "625", "description": "Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas" } ], "efirma": { "active": true, "valid_from": "2024-03-02", "valid_to": "2028-03-02" }, "csd": { "active": false, "valid_from": null, "valid_to": null }, "third_party_invoicing": { "eligible": true, "reason": null }, "validation_url": "https://siat.sat.gob.mx/app/qr/faces/pages/mobile/validadorqr.jsf?D1=10&D2=1&D3=89097221992_HEGL900101K44" }, "created_at": "2026-10-12T15:04:05.115Z", "updated_at": "2026-10-12T15:04:41.203Z" }}