Webhooks

Webhooks let Bundata send HTTP callbacks to your endpoint when certain events occur—for example, when an extraction run or workflow run completes or fails. Use webhooks for monitoring, alerting, and integrating with your own systems (e.g. Slack, PagerDuty, or a custom pipeline).

What events are available

• Extraction run completed — Fired when an extraction job finishes (success or partial). Payload typically includes run ID, status, document count, and (optionally) source lineage references.
• Extraction run failed — Fired when a run fails. Payload includes run ID, error code, and message. See Error codes.
• Workflow run completed / failed — Same idea for workflow runs; payload includes workflow ID, run ID, and step-level status where applicable.

Exact event types and payload shapes depend on your plan and product version. See the API or Platform webhook configuration for the full list.

How to set up webhooks

1. Create an endpoint — Expose an HTTPS URL that accepts POST requests. It should return 2xx quickly (process async if needed) so Bundata doesn’t retry unnecessarily.
2. Register the webhook — In the Platform (Settings or Integrations) or via API, register the URL and select the events you want. Optionally set a secret and verify signatures (see below).
3. Handle the payload — Parse the JSON payload, verify the signature if configured, and process the event (e.g. update a dashboard, trigger an alert, or enqueue a job).

Payload and signature

• Payload — JSON body with event type, timestamp, and event-specific data (run ID, status, errors). Include only non-sensitive identifiers; do not include document content or credentials.
• Signature — When you set a webhook secret, Bundata signs each request (e.g. X-Bundata-Signature header with HMAC). Verify the signature in your handler to ensure the request is from Bundata and unchanged. See your product docs for the exact header and algorithm.

Best practices

• Idempotency — Events may be delivered more than once (retries). Use event ID or (run ID + timestamp) to deduplicate.
• Quick response — Return 2xx within a few seconds. Do heavy work asynchronously so the webhook endpoint doesn’t time out and trigger retries.
• Security — Use HTTPS only; verify signatures; don’t expose internal secrets in the endpoint. Prefer a dedicated URL and secret for Bundata.

Retries and failures

• If your endpoint returns 4xx/5xx or times out, Bundata may retry according to a backoff schedule. Avoid unnecessary retries by returning 2xx once you’ve accepted the event and handling errors internally.
• Monitor failed deliveries in the Platform or via support if webhooks repeatedly fail.

Next steps

• Workflows monitoring — Run history and alerts.
• Error handling — Retries and error codes.
• Reference: API — Webhook registration API if available.