Skip to main content
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: 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 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. 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 endpoints to create, list, retrieve, update, and delete endpoints, and the Webhook Requests endpoints to inspect delivery attempts.

​
Event payload

Each delivery’s body is a single Event object. The event includes the type that occurred, the source and resource IRIs, and a data object whose data.object holds the current state of the affected resource. Update events also include data.changes with the old and new values of the fields that changed. See Event examples for the full payload structure 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.