> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Entrega eventos de Syntage a tu servidor y administra los endpoints desde el dashboard o la API.

Los webhooks permiten que Syntage entregue eventos a tu servidor cuando los recursos de tu organización cambian. Úsalos cuando tu integración necesite reaccionar a nuevas credenciales, entidades, extracciones, facturas, archivos, reportes u otros recursos sin tener que hacer polling a la API de eventos.

## Endpoints de webhook

Un endpoint de webhook es la URL HTTPS donde Syntage envía los eventos que coinciden. Cada endpoint define:

| Campo | Propósito |
| - | - |
| `url` | La URL HTTPS pública que recibe las entregas de eventos |
| `events` | Los tipos de eventos que se entregan al endpoint, como `extraction.updated` o `invoice.created` |
| `enabled` | Si Syntage debe enviar eventos al endpoint |
| `contentType` | El formato del payload, ya sea `application/ld+json` o `application/json` |
| `signingSecret` | El secreto utilizado para verificar las firmas de las entregas |

Las URLs de los endpoints deben usar HTTPS y deben resolverse a una dirección de red pública. Syntage envía cada entrega como una solicitud `POST` con los encabezados `X-Syntage-Signature`, `X-Satws-Signature`, `Content-Digest` y `Content-Type`.

Consulta [Validación de solicitudes de webhook](https://docs.syntage.com/guides/validating-webhook-requests.md) para verificar que las entregas de webhook provengan de Syntage.

## Administrar webhooks

Puedes administrar los endpoints de webhook desde el dashboard o desde la API. Ambos actúan sobre los mismos endpoints, por lo que un endpoint creado en el dashboard es visible a través de la API y viceversa.

### Desde el dashboard

Los administradores pueden administrar los webhooks en el dashboard, en [Configuración → Webhooks](https://app.syntage.com/settings/webhooks). Desde ahí puedes:

* Crear un endpoint ingresando su URL HTTPS y seleccionando los tipos de eventos que se entregarán.
* Habilitar o deshabilitar un endpoint sin eliminarlo.
* Ver el `signingSecret` que se usa para verificar las entregas.
* Revisar los intentos de entrega recientes para monitorear el estado del endpoint.

### Desde la API

Para administrar los webhooks de forma programática, usa los endpoints de [Webhook Endpoints](https://docs.syntage.com/api-reference/webhook-endpoints/list-all-webhook-endpoints.md) para crear, listar, recuperar, actualizar y eliminar endpoints, y los endpoints de [Webhook Requests](https://docs.syntage.com/api-reference/webhook-requests/list-all-webhook-requests.md) para inspeccionar los intentos de entrega.

## Cuerpo del evento

El cuerpo de cada entrega es un único objeto [Event](https://docs.syntage.com/es/resources/core/events.md). El evento incluye el `type` que ocurrió, las IRIs `source` y `resource`, y un campo `data`. En los eventos de creación y actualización, `data.object` contiene el estado del recurso afectado al momento en que se creó el evento, y los eventos de actualización también incluyen `data.changes` con los valores anteriores y nuevos de los campos que cambiaron. Los eventos de eliminación conservan la IRI `resource`, pero no incluyen el recurso, por lo que su `data` es un arreglo vacío.

El tamaño del payload de un webhook varía según el recurso subyacente y puede alcanzar decenas de megabytes. Configura tu endpoint y cualquier proxy inverso para aceptar cuerpos de solicitud grandes; recomendamos permitir al menos 100 MB. Esta recomendación no representa un tamaño máximo del payload.

Consulta [Ejemplos de eventos](https://docs.syntage.com/es/developers/event-examples.md) para ver payloads de ejemplo de los eventos de creación, actualización y eliminación.

## Solicitudes de webhook

Una solicitud de webhook es un intento de entrega de Syntage a un endpoint de webhook. Los registros de solicitudes son útiles para monitorear el estado de las entregas e investigar fallas.

Syntage registra la URL del endpoint, el evento relacionado, el código de estado de la respuesta, el tiempo de respuesta y las marcas de tiempo. Si Syntage no puede obtener una respuesta HTTP, por ejemplo cuando la solicitud expira después de 3 segundos, el `responseStatusCode` registrado es `0`.

Las entregas se consideran exitosas cuando tu endpoint devuelve un código de estado HTTP `2xx`. Las entregas fallidas se reintentan hasta 4 veces, por lo que tu manejador de webhooks debe procesar los eventos de manera idempotente.

El orden de entrega de los webhooks y la entrega exactamente una vez no están garantizados. Tu endpoint puede recibir eventos fuera de orden y el mismo evento puede entregarse más de una vez. Almacena el ID de cada evento y deduplica su procesamiento; no debes asumir que el orden en que llegan los eventos coincide con el orden en que ocurrieron los cambios subyacentes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.