Webhook Management API

Everything the Events page in the app does to a webhook subscription is available over the v1 API: create and update subscriptions, verify the endpoint, pause and resume delivery, rotate the signing secret, read the delivery log, read aggregated metrics, and re-queue failed deliveries.

For the payload shapes your endpoint receives, and for signature verification, see Webhook Setup. For the same operations from a terminal, see the limai webhooks command group.

Base Path and Authentication

Every route lives under the project that owns the subscription:

https://app.limai.io/api/v1/projects/{projectId}/webhooks

All routes take a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

An API token inherits the role of the user who created it, and every webhook route -- including the read-only ones -- requires the EDIT_MODELS permission. That means OWNER and DEVELOPER only. A token belonging to a USER gets 403 on GET just as it does on DELETE; there is no read-only tier for webhooks. A project-scoped token can only reach its own project.

The Webhook Object

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED",
    "DOCUMENT_EXTRACTION_FAILED"
  ],
  "isActive": true,
  "isVerified": false,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T09:00:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": []
}

A subscription only receives deliveries when isActive and isVerified are both true. Creating a subscription sets isVerified to false; so does changing its url, and so does rotating its secret. After any of those, verify again or nothing will be delivered.

secretKey is not part of this object. It is returned exactly twice in a subscription's life: on create and on rotate secret. Store it when you see it -- no route reads it back.

Routes and Route IDs

A subscription is routed by the deployments, agents, classifiers and splitters it listens to. Which family a given event needs is described in Routing Families; the API enforces the same rule, so a subscription that selects a document event without a deployment route is rejected with 400.

Route ID arrays behave the same way everywhere:

• Each array holds at most 100 IDs, and the IDs within one array must be unique.
• Every ID must belong to this project. Classifiers are the one exception: a global classifier in the same organization is accepted.
• On update, a supplied array replaces that family's routes wholesale. Omitting the array leaves that family untouched; sending an empty array clears it.

List Webhooks

Returns every webhook subscription in the project, newest first.

Parameters

Request

const res = await fetch(
"https://app.limai.io/api/v1/projects/proj_abc123/webhooks",
{
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
  },
}
);
const { webhooks } = await res.json();

Response

{
  "webhooks": [
    {
      "id": "whk_abc123",
      "projectId": "proj_abc123",
      "url": "https://example.com/hooks/limai",
      "events": [
        "DOCUMENT_EXTRACTED"
      ],
      "isActive": true,
      "isVerified": true,
      "createdAt": "2026-08-26T09:00:00.000Z",
      "updatedAt": "2026-08-26T09:04:00.000Z",
      "deployments": [
        {
          "id": "dep_123abc",
          "name": "Invoices",
          "type": "MODEL"
        }
      ],
      "agents": [],
      "classifiers": [],
      "splitters": []
    }
  ]
}

Create a Webhook

Creates a subscription and returns it with its signing secret. This is one of only two responses that ever carries secretKey.

Every field is optional, which lets you create a draft and fill it in later. The subscription is created with isActive: true only when it is fully configured -- a URL, at least one event, and at least one route. Anything less is created inactive. isVerified is always false on create.

Parameters

Request

const res = await fetch(
"https://app.limai.io/api/v1/projects/proj_abc123/webhooks",
{
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/hooks/limai",
    events: ["DOCUMENT_EXTRACTED", "DOCUMENT_EXTRACTION_FAILED"],
    deploymentIds: ["dep_123abc"],
  }),
}
);
const webhook = await res.json();
storeSecret(webhook.secretKey);

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED",
    "DOCUMENT_EXTRACTION_FAILED"
  ],
  "isActive": true,
  "isVerified": false,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T09:00:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": [],
  "secretKey": "9f2c4b6d8e0a1c3e5f7a9b1d3f5a7c9e1b3d5f7a9c1e3f5a7b9d1f3a5c7e9b1d"
}

Errors

Get a Webhook

Returns one subscription. No secret.

Parameters

Request

curl "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED"
  ],
  "isActive": true,
  "isVerified": true,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T09:04:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": []
}

Update a Webhook

Updates the fields you send and leaves the rest alone. At least one field is required -- an empty body is a 400.

Changing url sets isVerified back to false. Deliveries stop until you verify the new URL.

Parameters

Request

await fetch(
"https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123",
{
  method: "PATCH",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: ["DOCUMENT_EXTRACTED", "DOCUMENT_VALIDATED"],
    deploymentIds: ["dep_123abc", "dep_456def"],
  }),
}
);

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED",
    "DOCUMENT_VALIDATED"
  ],
  "isActive": true,
  "isVerified": true,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T10:15:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    },
    {
      "id": "dep_456def",
      "name": "Receipts",
      "type": "PRODUCTION"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": []
}

Delete a Webhook

Deletes the subscription and its routes. Returns 204 with no body. This is not reversible; to stop delivery without losing the configuration, use pause.

Request

curl -X DELETE "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

204 No Content

Pause a Webhook

Sets isActive to false. Routes, events, secret and verification state are untouched, so resuming needs no re-verification. Returns the updated Webhook object.

Request

curl -X POST "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/pause" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED"
  ],
  "isActive": false,
  "isVerified": true,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T11:00:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": []
}

Resume a Webhook

Sets isActive to true. Delivery only actually restarts if the subscription is also verified.

Request

curl -X POST "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/resume" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED"
  ],
  "isActive": true,
  "isVerified": true,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T11:05:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": []
}

Verify a Webhook

Sends a signed VERIFICATION event to the subscription's URL. Your endpoint must echo the challenge value back in its response body. On success isVerified becomes true; on failure it is left alone.

This route's response shape differs from the rest: it is success plus message, not a Webhook object.

Verification pings are not written to the delivery log. They never appear in List Deliveries.

Request

curl -X POST "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "message": "Webhook URL verified successfully"
}

Endpoint Unreachable

When your endpoint refuses the challenge, times out, or answers with the wrong body, the route answers 502 with the same two fields:

{
  "success": false,
  "message": "Webhook endpoint responded with status 500"
}

A 400 here means something else: the subscription's URL or secret changed while the challenge was in flight (Webhook URL or secret changed during verification; verify again). Re-read the subscription and verify again.

Rotate the Signing Secret

Generates a new signing secret and returns the subscription with secretKey. Every event enqueued after the rotation is signed with the new secret.

Rotation does not reach into the delivery queue. A job captures the URL and secret at enqueue time and keeps them, so deliveries that were already queued or mid-retry when you rotated are still signed with the old secret -- and so is any retry of a delivery enqueued before the rotation. Automatic retries drain within a few minutes (five attempts, 10 s exponential backoff), but a retained payload can be retried by hand for about 7 days. Keep accepting the old secret alongside the new one for as long as you may retry such deliveries, rather than dropping it the moment you rotate.

Rotation also resets isVerified to false, because the challenge is signed with the secret. Verify again afterwards or delivery stays stopped.

Request

curl -X POST "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/rotate-secret" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "id": "whk_abc123",
  "projectId": "proj_abc123",
  "url": "https://example.com/hooks/limai",
  "events": [
    "DOCUMENT_EXTRACTED"
  ],
  "isActive": true,
  "isVerified": false,
  "createdAt": "2026-08-26T09:00:00.000Z",
  "updatedAt": "2026-08-26T12:00:00.000Z",
  "deployments": [
    {
      "id": "dep_123abc",
      "name": "Invoices",
      "type": "MODEL"
    }
  ],
  "agents": [],
  "classifiers": [],
  "splitters": [],
  "secretKey": "1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3f5a7b9d1f3a5c7e9b1d3f"
}

List Deliveries

Returns the delivery log for one subscription, newest first, with a total for pagination.

Parameters

Request

const params = new URLSearchParams({ status: "failed", limit: "50" });
const res = await fetch(
`https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/deliveries?${params}`,
{
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
  },
}
);
const { deliveries, total } = await res.json();

Response

{
  "deliveries": [
    {
      "eventId": "evt_1756199524000_k3f9x2mq7ab",
      "subscriptionId": "whk_abc123",
      "eventType": "DOCUMENT_EXTRACTED",
      "timestamp": "2026-08-26T09:12:04.000Z",
      "url": "https://example.com/hooks/limai",
      "status": "failed",
      "retryCount": 4,
      "routeFamily": "deployment",
      "responseCode": 500,
      "responseBody": "internal error",
      "errorType": "ENDPOINT_ERROR",
      "durationMs": 812,
      "deploymentId": "dep_123abc",
      "deploymentName": "Invoices"
    }
  ],
  "total": 137,
  "limit": 50,
  "offset": 0
}

The Delivery Object

Optional fields are omitted, not set to null.

Delivery Statuses

failed and dead_lettered describe the same delivery seen from two sides: the worker marks the last attempt failed, then the dead-letter hook marks the job dead_lettered. Both count as failures in metrics, and both are candidates for retry.

The log only holds events enqueued from 2026-08-26 onwards, when per-attempt recording shipped. See What the Delivery Log Does Not Tell You.

Get Metrics

Aggregated delivery counts for one subscription over a time window, broken down per route and bucketed into a time series.

Parameters

Request

curl "https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/metrics?window=7d&bucket=day" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "organizationId": "org_xyz789",
  "totalEvents": 420,
  "successfulEvents": 402,
  "failedEvents": 15,
  "pendingEvents": 3,
  "successRate": 95.71,
  "averageResponseTime": 214.5,
  "perRoute": [
    {
      "routeFamily": "deployment",
      "routeId": "dep_123abc",
      "routeName": "Invoices",
      "totalEvents": 380,
      "successfulEvents": 370,
      "failedEvents": 8,
      "pendingEvents": 2,
      "successRate": 97.37
    },
    {
      "routeFamily": "classifier",
      "routeId": "cls_456def",
      "routeName": "Inbound router",
      "totalEvents": 40,
      "successfulEvents": 32,
      "failedEvents": 7,
      "pendingEvents": 1,
      "successRate": 80
    }
  ],
  "series": [
    {
      "bucket": "2026-08-25T00:00:00.000Z",
      "successful": 210,
      "failed": 4,
      "pending": 0
    },
    {
      "bucket": "2026-08-26T00:00:00.000Z",
      "successful": 192,
      "failed": 11,
      "pending": 3
    }
  ],
  "window": "7d",
  "bucket": "day"
}

Each perRoute entry carries routeFamily (deployment, agent, classifier or splitter), routeId, routeName, its own totalEvents, successfulEvents, failedEvents and pendingEvents, and a successRate. routeName falls back to the ID if the route has since been deleted.

perRoute replaces the older perDeployment breakdown. Classification and splitting events have no deployment to key off, so a deployment-only breakdown could not represent them.

Retry Failed Deliveries

Re-queues deliveries that ended failed or dead_lettered. A retry replays the job as it was enqueued: the delivery goes to the URL and is signed with the secret captured at enqueue time, not the subscription's current ones. Changing the URL or rotating the secret does not redirect or re-sign a retried delivery -- re-drive the event from your own side if you need that.

Parameters

Request

const res = await fetch(
"https://app.limai.io/api/v1/projects/proj_abc123/webhooks/whk_abc123/retry",
{
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventIds: ["evt_1756199524000_k3f9x2mq7ab"],
  }),
}
);
const { retriedCount, skipped } = await res.json();

Response

{
  "retriedCount": 1,
  "retried": [
    {
      "eventId": "evt_1756199524000_k3f9x2mq7ab",
      "url": "https://example.com/hooks/limai"
    }
  ],
  "skipped": [
    {
      "eventId": "evt_1756199111000_p8q2r4s6t8u",
      "url": "https://example.com/hooks/limai",
      "reason": "payload_unavailable"
    }
  ],
  "message": "Re-queued 1 of 2 webhook deliveries; the rest are already in flight, or their original payload is no longer retained"
}

A 200 here means the request reached the delivery queue, not that anything was re-sent. Whether a given delivery actually went back on the queue is reported per delivery: everything in retried was re-queued, everything in skipped was not, with a reason. A 500 means the queue itself could not be reached.

Asking to retry an event ID that is not a failed delivery of this subscription is not an error either -- it is simply not among the candidates, and the response reads No failed webhook deliveries to retry.

How Far Back Retry Reaches

Retry replays the queued job's retained payload, not a copy in the database. The delivery log therefore outlives the ability to retry from it: a row can read failed long after its payload is gone.

• A failed delivery is retained on the delivery queue for 7 days, and only the most recent 5000 failures are kept. Whichever limit is hit first wins, so a high-volume project loses reach sooner than 7 days.
• A dead-lettered delivery is retained on the dead-letter queue, which is swept on the same 7 day retention. The dead-letter scan also stops after 5000 entries per queue state.

Past that, the delivery still appears in the log, but retry answers payload_unavailable. Re-drive it from your own side using the eventId and the source data instead.

Note that retriedCount counts deliveries put back on the queue, not deliveries that ultimately succeed. A re-queued delivery also keeps its attempt counter rather than starting a fresh set of five, so one that had already exhausted its attempts gets a single further attempt before it dead-letters again. See Retry Policy.

Error Responses

Every route on this page shares one error shape, an object with a single error string. The exception is verify, which reports endpoint failures as success: false plus a message, with status 502.

404 reads Webhook not found for a missing project too -- it does not distinguish the two.