Webhook Setup

Overview

Klarefi sends webhook events to notify your application when processing completes, documents are processed, or sessions change state. All webhooks are signed with HMAC-SHA256 for security.

Setting Up Webhooks

1. Register an Endpoint

Register a webhook endpoint in the Klarefi dashboard under Webhooks. You'll receive a signing secret (whsec_...) to verify incoming events.

2. Implement Your Receiver

Your endpoint must:

Accept POST requests with JSON body
Return a 2xx status code within 30 seconds
Verify the signature before processing

Signature Verification

Every webhook includes an X-Klarefi-Signature header:

X-Klarefi-Signature: t=1704067200,v1=abc123def456...

The signature is computed as: HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

TypeScript

import { verifyWebhookSignature } from "@klarefi/sdk";
import express from "express";

const app = express();

app.post(
  "/webhooks/klarefi",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const event = await verifyWebhookSignature(
        req.body.toString(),
        req.headers["x-klarefi-signature"] as string,
        "whsec_your_signing_secret",
      );

      switch (event.event) {
        case "case.completed":
          console.log("Case completed:", event.case_id);
          // Process the results in event.data
          break;
        case "document.processed":
          console.log("Document processed:", event.case_id);
          break;
        default:
          console.log("Unhandled event:", event.event);
      }

      res.sendStatus(200);
    } catch (err) {
      console.error("Webhook verification failed:", err);
      res.sendStatus(401);
    }
  },
);

Python

from klarefi import verify_webhook_signature, WebhookVerificationError
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/klarefi", methods=["POST"])
def handle_webhook():
    try:
        event = verify_webhook_signature(
            raw_body=request.get_data(as_text=True),
            signature_header=request.headers.get("X-Klarefi-Signature"),
            signing_secret="whsec_your_signing_secret",
        )

        if event["event"] == "case.completed":
            print("Case completed:", event["case_id"])
            # Process the results in event["data"]

        return "", 200

    except WebhookVerificationError as e:
        print("Webhook verification failed:", e)
        return "", 401

Event Types

Event	Description
`session.created`	New intake session created
`document.uploaded`	Document uploaded to a session
`document.processed`	Document extraction completed
`skill.resolved`	A skill extraction reached a decision
`skill.needs_review`	A skill extraction needs human review
`session.complete`	All required skills resolved
`session.submitted_incomplete`	Session submitted without full resolution
`session.expired`	Session TTL expired

Testing Webhooks

Send a test event to verify your receiver works before going live:

curl -X POST https://api.klarefi.com/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://your-app.com/webhooks/klarefi",
    "signing_secret": "whsec_your_signing_secret"
  }'

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 5 total attempts (1 initial + 4 retries), the delivery is marked as failed. Check the delivery log in the dashboard for troubleshooting.

Overview

Klarefi sends webhook events to notify your application when processing completes, documents are processed, or sessions change state. All webhooks are signed with HMAC-SHA256 for security.

Setting Up Webhooks

1. Register an Endpoint

Register a webhook endpoint in the Klarefi dashboard under Webhooks. You'll receive a signing secret (whsec_...) to verify incoming events.

2. Implement Your Receiver

Your endpoint must:

Accept POST requests with JSON body
Return a 2xx status code within 30 seconds
Verify the signature before processing

Signature Verification

Every webhook includes an X-Klarefi-Signature header:

X-Klarefi-Signature: t=1704067200,v1=abc123def456...

The signature is computed as: HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

TypeScript

import { verifyWebhookSignature } from "@klarefi/sdk";
import express from "express";

const app = express();

app.post(
  "/webhooks/klarefi",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const event = await verifyWebhookSignature(
        req.body.toString(),
        req.headers["x-klarefi-signature"] as string,
        "whsec_your_signing_secret",
      );

      switch (event.event) {
        case "case.completed":
          console.log("Case completed:", event.case_id);
          // Process the results in event.data
          break;
        case "document.processed":
          console.log("Document processed:", event.case_id);
          break;
        default:
          console.log("Unhandled event:", event.event);
      }

      res.sendStatus(200);
    } catch (err) {
      console.error("Webhook verification failed:", err);
      res.sendStatus(401);
    }
  },
);

Python

from klarefi import verify_webhook_signature, WebhookVerificationError
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/klarefi", methods=["POST"])
def handle_webhook():
    try:
        event = verify_webhook_signature(
            raw_body=request.get_data(as_text=True),
            signature_header=request.headers.get("X-Klarefi-Signature"),
            signing_secret="whsec_your_signing_secret",
        )

        if event["event"] == "case.completed":
            print("Case completed:", event["case_id"])
            # Process the results in event["data"]

        return "", 200

    except WebhookVerificationError as e:
        print("Webhook verification failed:", e)
        return "", 401

Event Types

Event	Description
`session.created`	New intake session created
`document.uploaded`	Document uploaded to a session
`document.processed`	Document extraction completed
`skill.resolved`	A skill extraction reached a decision
`skill.needs_review`	A skill extraction needs human review
`session.complete`	All required skills resolved
`session.submitted_incomplete`	Session submitted without full resolution
`session.expired`	Session TTL expired

Testing Webhooks

Send a test event to verify your receiver works before going live:

curl -X POST https://api.klarefi.com/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://your-app.com/webhooks/klarefi",
    "signing_secret": "whsec_your_signing_secret"
  }'

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 5 total attempts (1 initial + 4 retries), the delivery is marked as failed. Check the delivery log in the dashboard for troubleshooting.

Accept POST requests with JSON body
Return a 2xx status code within 30 seconds
Verify the signature before processing

Signature Verification

Every webhook includes an X-Klarefi-Signature header:

X-Klarefi-Signature: t=1704067200,v1=abc123def456...

The signature is computed as: HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

TypeScript

import { verifyWebhookSignature } from "@klarefi/sdk";
import express from "express";

const app = express();

app.post(
  "/webhooks/klarefi",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const event = await verifyWebhookSignature(
        req.body.toString(),
        req.headers["x-klarefi-signature"] as string,
        "whsec_your_signing_secret",
      );

      switch (event.event) {
        case "case.completed":
          console.log("Case completed:", event.case_id);
          // Process the results in event.data
          break;
        case "document.processed":
          console.log("Document processed:", event.case_id);
          break;
        default:
          console.log("Unhandled event:", event.event);
      }

      res.sendStatus(200);
    } catch (err) {
      console.error("Webhook verification failed:", err);
      res.sendStatus(401);
    }
  },
);

Python

from klarefi import verify_webhook_signature, WebhookVerificationError
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/klarefi", methods=["POST"])
def handle_webhook():
    try:
        event = verify_webhook_signature(
            raw_body=request.get_data(as_text=True),
            signature_header=request.headers.get("X-Klarefi-Signature"),
            signing_secret="whsec_your_signing_secret",
        )

        if event["event"] == "case.completed":
            print("Case completed:", event["case_id"])
            # Process the results in event["data"]

        return "", 200

    except WebhookVerificationError as e:
        print("Webhook verification failed:", e)
        return "", 401

Event Types

Event	Description
`session.created`	New intake session created
`document.uploaded`	Document uploaded to a session
`document.processed`	Document extraction completed
`skill.resolved`	A skill extraction reached a decision
`skill.needs_review`	A skill extraction needs human review
`session.complete`	All required skills resolved
`session.submitted_incomplete`	Session submitted without full resolution
`session.expired`	Session TTL expired

Testing Webhooks

Send a test event to verify your receiver works before going live:

curl -X POST https://api.klarefi.com/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://your-app.com/webhooks/klarefi",
    "signing_secret": "whsec_your_signing_secret"
  }'

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 5 total attempts (1 initial + 4 retries), the delivery is marked as failed. Check the delivery log in the dashboard for troubleshooting.

Webhook Setup

Overview

Setting Up Webhooks

1. Register an Endpoint

2. Implement Your Receiver

Signature Verification

TypeScript

Python

Event Types

Testing Webhooks

Retry Policy

On this page

Webhook Setup

Overview

Setting Up Webhooks

1. Register an Endpoint

2. Implement Your Receiver

Signature Verification

TypeScript

Python

Event Types

Testing Webhooks

Retry Policy

On this page

Webhook Setup

Overview

Setting Up Webhooks

1. Register an Endpoint

2. Implement Your Receiver

Signature Verification

TypeScript

Python

Event Types

Testing Webhooks

Retry Policy

On this page