> ## 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

> Deliver Syntage events to your server and manage endpoints from the dashboard or API.

Webhooks let Syntage deliver events to your server when resources in your organization change. Use them when your integration needs to react to new credentials, entities, extractions, invoices, files, reports, or other resources without polling the Events API.

## Webhook Endpoints

A webhook endpoint is the HTTPS URL where Syntage sends matching events. Each endpoint defines:

| Field | Purpose |
| - | - |
| `url` | The public HTTPS URL that receives event deliveries |
| `events` | The event types delivered to the endpoint, such as `extraction.updated` or `invoice.created` |
| `enabled` | Whether Syntage should send events to the endpoint |
| `contentType` | The payload format, either `application/ld+json` or `application/json` |
| `signingSecret` | The secret used to verify delivery signatures |

Endpoint URLs must use HTTPS and must resolve to a public network address. Syntage sends each delivery as a `POST` request with `X-Syntage-Signature`, `X-Satws-Signature`, `Content-Digest`, and `Content-Type` headers.

Use [Validating Webhook Requests](https://docs.syntage.com/guides/validating-webhook-requests.md) to verify that webhook deliveries came from Syntage.

## Managing webhooks

You can manage webhook endpoints from the dashboard or the API. Both act on the same endpoints, so an endpoint created in the dashboard is visible over the API and vice versa.

### From the dashboard

Administrators can manage webhooks in the dashboard under [Settings → Webhooks](https://app.syntage.com/settings/webhooks). From there you can:

* Create an endpoint by entering its HTTPS URL and selecting the event types to deliver.
* Enable or disable an endpoint without deleting it.
* View the `signingSecret` used to verify deliveries.
* Review recent delivery attempts to monitor endpoint health.

### From the API

To manage webhooks programmatically, use the [Webhook Endpoints](https://docs.syntage.com/api-reference/webhook-endpoints/list-all-webhook-endpoints.md) endpoints to create, list, retrieve, update, and delete endpoints, and the [Webhook Requests](https://docs.syntage.com/api-reference/webhook-requests/list-all-webhook-requests.md) endpoints to inspect delivery attempts.

## Event payload

Each delivery's body is a single [Event](https://docs.syntage.com/resources/core/events.md) object. The event includes the `type` that occurred, the `source` and `resource` IRIs, and a `data` field. For created and updated events, `data.object` holds the state of the affected resource when the event was created, and update events also include `data.changes` with the old and new values of the fields that changed. Deleted events keep the `resource` IRI but don't include the resource, so their `data` is an empty array.

Webhook payload size varies with the underlying resource and may reach tens of megabytes. Configure your endpoint and any reverse proxies to accept large request bodies; we recommend allowing at least 100 MB. This recommendation is not a maximum payload size.

See [Event examples](https://docs.syntage.com/developers/event-examples.md) for example payloads of created, updated, and deleted events.

## Webhook Requests

A webhook request is a delivery attempt from Syntage to a webhook endpoint. Request records are useful for monitoring delivery health and investigating failures.

Syntage records the endpoint URL, related event, response status code, response time, and timestamps. If Syntage cannot get an HTTP response, such as when the request times out after 3 seconds, the recorded `responseStatusCode` is `0`.

Deliveries are considered successful when your endpoint returns a `2xx` HTTP status code. Failed deliveries are retried up to 4 times, so your webhook handler should process events idempotently.

Webhook delivery order and exactly-once delivery are not guaranteed. Your endpoint may receive events out of order, and the same event may be delivered more than once. Store each event ID and deduplicate your processing; do not assume that the order in which events arrive matches the order in which the underlying changes occurred.


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