Webhooks

How a webhook fires ​

A webhook is a workspace-level endpoint definition. It receives events in two ways:

• Stage bindings. A pipeline stage can name an entry webhook, called when the stage starts (<stage>.entered), and an exit webhook, called when it finishes (<stage>.exited). In Studio these are set in the Webhooks section of a stage inspector.
• Event subscriptions. A webhook's events list opts it in to the job events in the catalogue below. These go only to webhooks that the job's pipeline references in a stage binding; a webhook with no events receives its stage-binding events only.

A job captures its pipeline's webhooks when it is submitted, so changing a binding affects jobs submitted afterwards.

Create a webhook ​

curl -X POST https://api.us.idpforge.cloud/v1/webhooks \
  -H "X-API-Key: $IDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AP team — pipeline events",
    "url": "https://hooks.acme.com/ap-events",
    "auth_type": "API_KEY",
    "auth": { "header_name": "X-API-Key", "api_key": "..." },
    "events": ["job.failed", "job.review_required"]
  }'

Event catalogue ​

Stage events ​

Delivered to the webhook bound to that stage's entry or exit.

Parse, split and classify, extract and post-processing fire once per document and set document_id. Studio offers entry and exit bindings on the initialization, parse, split_classify, extract and post_processing stages. A binding for source.entered or the edit stage is accepted but never fires.

Job events ​

Delivered to webhooks that list the event in events.

Job events carry an empty data object — read the job with GET /v1/jobs/{job_id} for the details.

Payload ​

{
  "id": "0191f3a4-1b2c-7d3e-8f40-5a6b7c8d9e0f",
  "type": "extract.exited",
  "timestamp": 1789107238,
  "job_id": "0191f3a2-7c4e-7b1d-9a55-3e0c8f2d6b41",
  "document_id": "0191f3a3-9e8d-7c6b-a5f4-3e2d1c0b9a87",
  "stage": "extract",
  "transition": "exited",
  "data": {
    "job": {
      "job_id": "0191f3a2-7c4e-7b1d-9a55-3e0c8f2d6b41",
      "status": "processing",
      "execution_mode": "async",
      "priority": "standard"
    }
  }
}

Verifying the signature ​

import hashlib
import hmac

def verify(secret: str, signature_header: str | None, raw_body: bytes) -> bool:
    if not signature_header:
        return False
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, signatureHeader: string | null, rawBody: Buffer): boolean {
  if (!signatureHeader) return false;
  const expected = Buffer.from(
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"),
  );
  const received = Buffer.from(signatureHeader);
  return received.length === expected.length && timingSafeEqual(expected, received);
}

Retries ​

A delivery succeeds on any 2xx response. Anything else is retried: 3xx (redirects are not followed), 4xx, 5xx, a connection failure, or no response within 30 seconds (10 seconds to connect).

A delivery gets up to 10 attempts. The wait before each retry doubles, from 4 seconds to about 17 minutes, so a delivery that keeps failing is abandoned roughly 35 minutes after the first attempt. Every retry resends the same body, signature and delivery id. Return 2xx as soon as you have stored the event, and do the slow work afterwards.