Get Started

# Webhooks

Get results at your own URL when a lookup runs longer than an HTTP request should wait: send webhook_url, receive 202 at once, and the result as a POST when it is ready.

Long-running endpoints can deliver their results to a webhook URL of your choosing rather than holding the HTTP connection open. This is how /v1/rfc/verify-batch works exclusively, and it is an option on /v1/rfc/validate, /v1/rfc/find-zip, and /v1/rfc/commerce-registry.

## How it works

- Pass `webhook_url` in the request body. http or https only. Redirects are not followed. Max length: 2048 characters.
- The API immediately returns 202 Accepted with a small status envelope, then continues processing.
- Once SAT replies, we POST a JSON payload to your URL. The payload's status/body envelope mirrors the synchronous response.

## Payload shape

POST to your webhook_url

```json
{
  "status": 200,
  "body": {
    "rfc": "XAXX010101000",
    "valid": true,
    "message": "RFC válido, puede ser utilizado en comprobantes",
    "...": "rest of the endpoint's normal response body"
  }
}
```

## Receiving webhooks

- Respond with any 2xx status as quickly as possible. We treat anything else as a delivery failure.
- Webhooks are best-effort. Each result is sent once, with a 30-second timeout, and is not retried, so keep your endpoint reachable.
- Always validate the rfc in the body matches a request you sent. Don't trust a webhook payload to identify which user it belongs to; use a tenant-scoped URL or include a token in the path.

## Local testing

Use a tunnel like ngrok, Cloudflare Tunnel, or Tailscale Funnel to expose your local dev server. We do not need to reach you from inside a private network. Any publicly resolvable URL will do.