Set up outbound webhooks

1. Build an HTTPS receiver that preserves the raw request body.
2. Add the endpoint and choose its event subscriptions.
3. Install the Karsa-generated Ed25519 public key in your receiver.
4. Complete Karsa’s endpoint-verification challenge.
5. Send a test event and inspect its delivery history.
6. Enable production event processing and handle retries safely.

​

Before you begin

• A source API credential or access to Settings → Integrations in Karsa.
• A publicly reachable HTTPS endpoint for production.
• A receiver that can read the unmodified request bytes and return a 2xx quickly.
• A secure location for the Ed25519 public key and endpoint metadata.

​

Events available in version 1

​

1. Obtain the verification public key

​

2. Implement the receiver

1. Reads the request as raw bytes.
2. Extracts the Karsa signature headers.
3. Selects the public key identified by Karsa-Webhook-Key-Version.
4. Verifies the Ed25519 signature before parsing JSON.
5. Returns the verification challenge when the event type is webhook.endpoint.verification.
6. Stores the immutable event ID as a deduplication key.
7. Queues business processing and returns a 2xx promptly.

​

Express example

import { createPublicKey, timingSafeEqual, verify } from "node:crypto";
import express from "express";

const app = express();

// Load this from your secret/configuration store, not from source control.
const publicKeys = new Map([["1", process.env.KARSA_WEBHOOK_PUBLIC_KEY_V1!]]);

function requiredHeader(request: express.Request, name: string): string {
  const value = request.header(name);
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

function sameText(left: string, right: string): boolean {
  const leftBytes = Buffer.from(left, "utf8");
  const rightBytes = Buffer.from(right, "utf8");
  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
}

app.post(
  "/webhooks/karsa",
  express.raw({ type: "application/json", limit: "256kb" }),
  async (request, response) => {
    try {
      const rawBody = request.body as Buffer;
      const eventId = requiredHeader(request, "Karsa-Webhook-Id");
      const eventType = requiredHeader(request, "Karsa-Webhook-Type");
      const timestamp = requiredHeader(request, "Karsa-Webhook-Timestamp");
      const version = requiredHeader(request, "Karsa-Webhook-Version");
      const keyVersion = requiredHeader(request, "Karsa-Webhook-Key-Version");
      const signatureHeader = requiredHeader(request, "Karsa-Webhook-Signature");

      if (version !== "1") {
        return response.status(400).json({ error: "Unsupported webhook version" });
      }

      const publicKeyPem = publicKeys.get(keyVersion);
      const encodedSignature = signatureHeader.match(/^v1=([A-Za-z0-9_-]+)$/u)?.[1];
      if (!publicKeyPem || !encodedSignature) {
        return response.status(401).json({ error: "Unknown key or signature version" });
      }

      // Karsa signs the exact UTF-8 bytes: timestamp + "." + raw request body.
      const signedBytes = Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), rawBody]);
      const valid = verify(
        null,
        signedBytes,
        createPublicKey(publicKeyPem),
        Buffer.from(encodedSignature, "base64url"),
      );
      if (!valid) {
        return response.status(401).json({ error: "Invalid signature" });
      }

      const event = JSON.parse(rawBody.toString("utf8")) as {
        id: string;
        type: string;
        challenge?: string;
      };

      if (!sameText(event.id, eventId) || !sameText(event.type, eventType)) {
        return response.status(400).json({ error: "Header and body mismatch" });
      }

      if (event.type === "webhook.endpoint.verification") {
        return response.status(200).json({ challenge: event.challenge });
      }

      // This operation inserts event.id behind a unique constraint, queues
      // new events, and treats a duplicate ID as already accepted.
      await acceptWebhookEventOnce(event);
      return response.status(204).send();
    } catch {
      return response.status(400).json({ error: "Invalid webhook request" });
    }
  },
);

​

3. Add the endpoint in Karsa

1. Open Settings → Integrations.
2. Select the ingestion source that owns the endpoint.
3. In Webhooks, choose Add endpoint.
4. Enter a recognizable name and the receiver’s HTTPS URL.
5. Select the KYB event types the destination should receive.
6. Save the endpoint.
7. Copy the generated public key into your receiver configuration.

​

API alternative

POST /api/ingestion/webhook-endpoints
Authorization: Bearer <source-credential>
Content-Type: application/json

{
  "name": "Production KYB receiver",
  "url": "https://api.example.com/webhooks/karsa",
  "eventTypes": ["kyb.evaluation.queued", "kyb.evaluation.completed", "kyb.evaluation.failed"]
}

​

4. Verify the endpoint

POST /api/ingestion/webhook-endpoints/{endpointId}/verify
Authorization: Bearer <source-credential>

{
  "challenge": "the-exact-value-from-the-request"
}

​

5. Send a test event

• Signature verification succeeds against the advertised key version.
• The header event ID and event type match the JSON body.
• The event ID is stored as a deduplication key.
• Your receiver returns a 2xx after durable acceptance.
• The Karsa delivery history shows DELIVERED.

​

Request headers

​

Event envelope

{
  "id": "7ca98328-1d7f-4ccb-8bd9-299373dbade2",
  "type": "kyb.evaluation.completed",
  "version": "1",
  "createdAt": "2026-08-27T13:22:16.155Z",
  "source": {
    "id": "source_record_id",
    "key": "source-stable-key"
  },
  "subject": {
    "type": "customer",
    "id": "customer_resource_id"
  },
  "data": {
    "evaluationId": "evaluation_record_id",
    "workflowRunId": "workflow_run_id",
    "status": "COMPLETED",
    "outcome": "NO_ATTENTION",
    "failureCode": null
  }
}

​

Delivery and retry behavior

​

Which endpoints receive an event

​

Catch up on missed events

GET /api/ingestion/webhook-events?since=2026-09-25T00:00:00Z&limit=100
Authorization: Bearer <source-credential>

• Pass nextCursor as cursor to read the next page. nextCursor is null on the last page.
• type filters by event type; repeat it or separate values with commas. webhook.test events are excluded unless you request them. Endpoint verification challenges are not recorded.
• Events are listed for 30 days, the same window as delivery history. Older events and a since before that window are not returned.
• To resume later, pass the createdAt of the last event you stored as since, starting a few minutes earlier: an event can become visible shortly after its createdAt. Skip IDs you already stored.

​

Replay missed events

POST /api/ingestion/webhook-endpoints/{endpointId}/replay-missing
Authorization: Bearer <source-credential>
Content-Type: application/json

{ "since": "2026-09-27T12:00:00Z" }

{ "replayed": 3, "skippedAlreadyDelivered": 12, "capped": false }

• Karsa queues a delivery to this endpoint for every recorded event of your source that was created at or after since, has a type the endpoint subscribes to now, and was never queued for this endpoint. Events the endpoint already has a delivery for, in any state, are counted in skippedAlreadyDelivered and not sent again; use manual retry for dead-lettered ones. webhook.test events are never replayed.
• The endpoint must be ACTIVE; otherwise the call returns 409 with WEBHOOK_NOT_ACTIVE.
• since is limited to the 30-day history window; an earlier value starts at the window.
• Each call queues at most 500 events, oldest first. When capped is true, call again with the same since to queue the rest. Repeating a call never queues an event twice.
• A replayed delivery has the original event ID in Karsa-Webhook-Id and the original envelope as its body, so your inbox deduplicates it like any retry. JSON key order can differ from the body other endpoints received.
• A replayed delivery is signed when it is queued, with the endpoint’s current active key, and Karsa-Webhook-Timestamp is that time rather than the event’s createdAt. A replay is a new delivery with its own full retry window, and within it every attempt keeps the same timestamp and signature, so a timestamp policy that allows the retry window also accepts replays of older events.
• OIDC service principals need the karsa:webhooks:manage scope. The call is audit-logged and shares your source’s request rate limit.

​

Duplicate handling and ordering

1. Verify the signature and header/body agreement.
2. Insert the event ID and raw payload into an inbox table with a unique constraint.
3. If the event ID already exists, return a 2xx without applying it again.
4. Commit the inbox record.
5. Process the event asynchronously and idempotently.

​

Rotate signing keys

• Keep both public-key versions in your receiver’s key map.
• Select the key using Karsa-Webhook-Key-Version.
• Do not replace the old key until its overlap status becomes RETIRED.
• Remember that previously queued deliveries remain pinned to their original key and signature.

​

Replay a failed delivery

​

Troubleshooting

​

Go-live checklist

• The production URL uses HTTPS and does not redirect.
• Raw-body signature verification runs before JSON parsing.
• Public keys are selected by key version and stored securely.
• Header event ID/type are compared with the body.
• Event IDs have a unique database constraint.
• Events are durably queued before returning 2xx.
• Processing is asynchronous and idempotent.
• Both active and overlapping public keys are accepted during rotation.
• Delivery failures and dead-lettered events are monitored.
• A test event succeeds from Karsa and appears in delivery history.