Webhook troubleshooting

”I’m not receiving webhooks”

Check the following:

1. The API key has webhookUrl configured (ask the administrator to confirm).
2. The URL is HTTPS and resolves to a valid public IP (not RFC1918 or link-local).
3. The endpoint responds with 2xx in under 10 s.
4. The document was issued via the API: documents issued from the web POS do not fire webhooks.
5. Hacienda has already responded. If the document is procesando, there is nothing to notify yet.

”I’m getting 401 or an invalid signature”

Check the following:

1. You are using the same webhookSecret that was generated when the key was created or rotated.
2. You read the raw body before parsing it (without re-serializing the JSON).
3. The comparison is performed with a timing-safe function (timingSafeEqual, hmac.compare_digest, hash_equals, etc.).
4. No spaces, BOM, or newlines are added to or removed from the body before computing the HMAC.

”I’m receiving the same event multiple times”

This is expected behavior during a retry. You must implement deduplication by nonce: the nonce changes on each attempt, so it works as the unique “delivery” key.

”I received the webhook, but the document doesn’t appear in GET /facturas/{clave}”

This is unlikely, but it can happen due to a race condition. Retry the GET with exponential backoff. If the situation persists for more than a minute, open a support ticket.