Webhooks

Register and manage the webhook that receives workflow and account events. For general Admin API information, see the Admin overview. A client may hold one active webhook at a time.

Everything on this page can also be done in the platform dashboard — registering the endpoint, switching payload mode, signing, custom headers, and inspecting recent deliveries. Use these endpoints when you want it in code; the two reach the same webhook.

webhook.set

Register the webhook. Enforces a maximum of one active webhook per client. There is no endpoint that changes the destination url – for that, delete the webhook and set a new one. Payload mode, signing and custom headers are all changeable in place.

curl -X POST https://api.linkedapi.io/admin/webhook.set \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "url": "https://example.com/hooks/linkedapi",
    "payloadMode": "fat"
  }'

Body:

• url – HTTPS endpoint that will receive deliveries. Required.
• payloadMode – fat (default) or thin. See payload modes. Optional.
• signingEnabled – true to sign every delivery. Defaults to false. When true, the response includes secret. See signature verification. Optional.
• headers – custom headers sent with every delivery, as a name-to-value object. See custom delivery headers. Optional.

Response:

{
  "success": true,
  "result": {
    "webhook": {
      "id": "whs-...",
      "url": "https://example.com/hooks/linkedapi",
      "payloadMode": "fat",
      "signingEnabled": false,
      "headerNames": [],
      "isActive": true,
      "createdAt": "2026-06-25T12:00:00.000Z"
    }
  }
}

• id – webhook identifier, used by the other endpoints.
• url – the registered destination.
• payloadMode – current payload mode.
• signingEnabled – whether deliveries are signed.
• headerNames – names of the configured custom headers, never their values.
• isActive – whether the webhook is active.
• createdAt – ISO 8601 timestamp.
• secret – the signing secret. Present only on a webhook.set that enabled signing, on webhook.setSigning when enabling, on webhook.revealSecret and on webhook.rotateSecret. Every other response omits it.

A url that is a bare IP address in a private or internal range is rejected. Deliveries are only ever sent to public addresses.

webhook.get

List the active webhook for this client. Returns an array with at most one entry. Never returns the signing secret – use webhook.revealSecret for that.

curl -X POST https://api.linkedapi.io/admin/webhook.get \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"

Response:

{
  "success": true,
  "result": {
    "webhooks": [
      {
        "id": "whs-...",
        "url": "https://example.com/hooks/linkedapi",
        "payloadMode": "fat",
        "signingEnabled": false,
        "headerNames": [],
        "isActive": true,
        "createdAt": "2026-06-25T12:00:00.000Z"
      }
    ]
  }
}

webhook.setPayloadMode

Switch the payload mode between fat and thin.

curl -X POST https://api.linkedapi.io/admin/webhook.setPayloadMode \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "payloadMode": "thin" }'

Body:

• id – webhook identifier. Required.
• payloadMode – fat or thin. Required.

webhook.setSigning

Turn signature verification on or off for this webhook. Returns the signing secret when enabling, so you can configure your verifier in the same step. No other endpoint changes the signing state.

curl -X POST https://api.linkedapi.io/admin/webhook.setSigning \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "signingEnabled": true }'

Body:

• id – webhook identifier. Required.
• signingEnabled – true to sign deliveries, false to stop. Required.

webhook.setHeader

Add or replace one custom header, leaving the others untouched. This is the endpoint to use when editing an existing configuration, because header values cannot be read back.

curl -X POST https://api.linkedapi.io/admin/webhook.setHeader \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "name": "Authorization", "value": "Bearer your_endpoint_token" }'

Body:

• id – webhook identifier. Required.
• name – header name. An existing header with the same name, ignoring case, is replaced. Required.
• value – header value. Required.

webhook.deleteHeader

Remove one custom header by name. The name is matched ignoring case.

curl -X POST https://api.linkedapi.io/admin/webhook.deleteHeader \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "name": "Authorization" }'

Body:

• id – webhook identifier. Required.
• name – header name to remove. Required.

webhook.setHeaders

Replace all custom headers at once. {} or null removes every header. Use this only when you hold every value – it is the programmatic path; for editing one header, use webhook.setHeader.

curl -X POST https://api.linkedapi.io/admin/webhook.setHeaders \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "headers": { "Authorization": "Bearer your_endpoint_token" } }'

Body:

• id – webhook identifier. Required.
• headers – name-to-value object, or null to clear. Required.

webhook.revealSecret

Return the current signing secret. Use it when you need the secret again after enabling signing – for example when configuring a second environment.

curl -X POST https://api.linkedapi.io/admin/webhook.revealSecret \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-..." }'

Body:

• id – webhook identifier. Required.

webhook.rotateSecret

Generate a new signing secret, store it and return it. This replaces a leaked secret without deleting the webhook, which would change its id.

curl -X POST https://api.linkedapi.io/admin/webhook.rotateSecret \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-..." }'

Body:

• id – webhook identifier. Required.

Rotation takes effect immediately and there is no overlap period: the old secret stops signing the moment the new one is stored, so every delivery fails verification until your endpoint holds the new value. Rotate when you are ready to deploy it.

webhook.delete

Delete the webhook. This is a soft delete: the delivery history is preserved and any still-pending deliveries are dropped. Because only active webhooks count toward the one-per-client limit, you can register a fresh webhook afterwards.

curl -X POST https://api.linkedapi.io/admin/webhook.delete \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-..." }'

Body:

• id – webhook identifier. Required.

webhook.deliveries

Return the most recent deliveries (newest first) as a debug feed – useful for confirming an endpoint is receiving and acknowledging events.

curl -X POST https://api.linkedapi.io/admin/webhook.deliveries \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"

Response:

{
  "success": true,
  "result": {
    "deliveries": [
      {
        "id": "whd-...",
        "eventType": "workflow.completed",
        "eventId": "workflow.completed:wf-...",
        "status": "success",
        "attempts": 1,
        "responseStatusCode": 200,
        "lastError": null,
        "createdAt": "2026-06-25T12:00:00.000Z",
        "updatedAt": "2026-06-25T12:00:01.000Z"
      }
    ]
  }
}

• id – delivery identifier, passed to webhook.replayDelivery.
• eventType – the event type that was delivered.
• eventId – the envelope id of the delivered event.
• status – pending, delivering, success, or failed.
• attempts – delivery attempts made so far.
• responseStatusCode – HTTP status your endpoint returned on the last attempt, or null.
• lastError – error text from the last failed attempt, or null.
• createdAt / updatedAt – ISO 8601 timestamps.

webhook.replayDelivery

Re-arm an already-settled (success or failed) delivery for redelivery. The same eventId is reused, so consumer-side deduplication still applies – this is a true redelivery, not a new event.

curl -X POST https://api.linkedapi.io/admin/webhook.replayDelivery \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "deliveryId": "whd-..." }'

Body:

• deliveryId – delivery identifier from webhook.deliveries. Required.

webhook.sendTest

Emit a synthetic webhook.test event to the active webhook through the normal delivery path. Its data carries a single message field. Use it to verify a freshly registered endpoint without waiting for a real event.

curl -X POST https://api.linkedapi.io/admin/webhook.sendTest \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"