Webhook Overview

Webhooks are the fastest way to connect Ocriva to your own systems. Instead of repeatedly asking the API "is it done yet?", Ocriva pushes a notification directly to your server the moment something happens — a document finishes processing, a batch completes, or a template is updated.

What Are Webhooks?

A webhook is an HTTP POST request that Ocriva sends to a URL you control whenever a specific event occurs. Your server receives a JSON payload with all the details of the event and can act on it immediately — insert a row into your database, send a Slack message, trigger a downstream workflow, or anything else your system needs to do.

Webhooks follow a simple publish/subscribe model:

1. You register an endpoint URL in Ocriva and choose which events you want to receive.
2. When one of those events fires, Ocriva makes an HTTP POST to your URL with the event payload.
3. Your server processes the payload and returns a 2xx status code to acknowledge delivery.

How Webhooks Fit the DAT Pipeline

Ocriva's core workflow — Document → AI → Transform — produces structured data from raw files. Webhooks are the bridge that carries that data from Ocriva into your systems automatically.

Your App          Ocriva                          Your System
   |                 |                                  |
   |-- Upload ------>|                                  |
   |                 |-- AI Extraction                  |
   |                 |-- Transform / Format             |
   |                 |-- Webhook POST ----------------->|
   |                 |                      Process data|
   |                 |                      Store result|
   |                 |                      Notify user |

The webhook fires after Ocriva has finished processing, so your endpoint always receives the final structured result — not a work-in-progress snapshot.

Webhook vs Polling

For production integrations with any meaningful volume, webhooks are strongly preferred.

Basic Flow: Invoice Processing Example

Here is what happens end-to-end when you process an invoice and receive the result via webhook:

1. Upload — Your app uploads invoice_march.pdf via the Ocriva API.
2. Processing — Ocriva's AI extracts fields (vendor, amount, line items, due date) using your configured template.
3. Webhook fires — Ocriva sends a document.processed event to your registered endpoint.
4. Your server receives — Your endpoint receives the JSON payload containing all extracted fields.
5. Your system acts — You insert the invoice into your ERP, trigger approval workflows, or notify the finance team.

{
  "eventType": "document.processed",
  "eventId": "evt_1743418800000_inv9x2",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_march_inv",
    "fileName": "invoice_march.pdf",
    "status": "completed",
    "extractedData": {
      "invoiceNumber": "INV-2026-0331",
      "vendor": "Acme Supplies Co.",
      "totalAmount": 15420.00,
      "currency": "THB",
      "dueDate": "2026-04-30"
    },
    "confidence": 0.97,
    "processingTime": 3241,
    "processedAt": "2026-03-31T12:00:00.000Z"
  }
}

Your server receives this payload and can immediately act on it — no polling, no waiting.

Security Overview

Every webhook delivery can include a cryptographic signature so you can verify the request genuinely came from Ocriva and was not tampered with in transit.

When you configure a secret on your webhook endpoint, Ocriva signs every delivery using HMAC-SHA256 and includes the signature in the X-Webhook-Signature header. Your server recomputes the signature using the same secret and compares — if they match, the request is authentic.

Delivery Headers

Every webhook request includes two standard headers:

Retry Policy

If your endpoint does not return a 2xx status code — or times out — Ocriva retries the delivery automatically:

• 3 total attempts (1 original + 2 retries)
• Exponential backoff between retries
• Every attempt is logged with status code, response time, and any error message

This means even transient failures on your side (a brief restart, a slow cold start) will not cause you to miss events permanently.

What's Next

• Event Types & Payloads — complete reference for all event types with payload examples
• Setup & Testing — create your first endpoint, verify signatures, and test locally