Managing 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, choosing events, 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, the event selection, 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"
  }'

const webhook = await admin.webhooks.set({
  url: "https://example.com/hooks/linkedapi",
  payloadMode: "fat",
});

from linkedapi import SetWebhookParams

webhook = admin.webhooks.set(
    SetWebhookParams(url="https://example.com/hooks/linkedapi", payload_mode="fat")
)

linkedin admin webhook set https://example.com/hooks/linkedapi --payload-mode fat --json

linkedin admin webhook set <url> [flags]

cat headers.json | linkedin admin webhook set https://example.com/hooks \
  --signing --events "workflow.*,inbox.messageReceived" --headers-stdin

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.
• events – the events to deliver: exact event types and <namespace>.* wildcards, such as ["workflow.completed", "inbox.*"]. Omitted or null means every event. See event selection. Optional.

Response:

{
  "success": true,
  "result": {
    "webhook": {
      "id": "whs-...",
      "url": "https://example.com/hooks/linkedapi",
      "payloadMode": "fat",
      "signingEnabled": false,
      "headerNames": [],
      "events": null,
      "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.
• events – the stored event selection, de-duplicated and sorted, or null for every event.
• 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"

const webhooks = await admin.webhooks.get();

webhooks = admin.webhooks.get()

linkedin admin webhook get --json

Response:

{
  "success": true,
  "result": {
    "webhooks": [
      {
        "id": "whs-...",
        "url": "https://example.com/hooks/linkedapi",
        "payloadMode": "fat",
        "signingEnabled": false,
        "headerNames": [],
        "events": null,
        "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" }'

await admin.webhooks.setPayloadMode({ id: "whs-...", payloadMode: "thin" });

from linkedapi import SetWebhookPayloadModeParams

admin.webhooks.set_payload_mode(
    SetWebhookPayloadModeParams(id="whs-...", payload_mode="thin")
)

linkedin admin webhook set-payload-mode whs-... thin --json

Body:

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

webhook.setEvents

Replace the event selection in place. null goes back to every event. Saving the selection the webhook already has, even reordered or with duplicates, changes nothing. Returns the updated webhook.

curl -X POST https://api.linkedapi.io/admin/webhook.setEvents \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "events": ["workflow.completed", "inbox.*"] }'

const webhook = await admin.webhooks.setEvents({
  id: "whs-...",
  events: ["workflow.completed", "inbox.*"],
});

from linkedapi import SetWebhookEventsParams

webhook = admin.webhooks.set_events(
    SetWebhookEventsParams(id="whs-...", events=["workflow.completed", "inbox.*"])
)

linkedin admin webhook set-events whs-... "workflow.completed,inbox.*" --json

linkedin admin webhook set-events <id> <events>
linkedin admin webhook set-events <id> --all

Body:

• id – webhook identifier. Required.
• events – exact event types and <namespace>.* wildcards, or null for every event. Required, so a request without it never clears a selection by accident.

An invalid entry is rejected with invalidRequestPayload naming it, and the stored selection stays as it was.

webhook.eventTypes

List the event types a selection can name, in the order Linked API defines them. webhook.test is not among them, because it is always delivered. It works before you register a webhook, so you can build a selection first.

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

const eventTypes = await admin.webhooks.eventTypes();

event_types = admin.webhooks.event_types()

linkedin admin webhook event-types --json

Response:

{
  "success": true,
  "result": {
    "eventTypes": [
      "workflow.created",
      "workflow.started",
      "workflow.completed",
      "account.active",
      "account.reconnectionRequired",
      "account.frozen",
      "account.deleted",
      "inbox.messageReceived",
      "inbox.messageSent",
      "network.connectionAccepted",
      "network.connectionAdded",
      "network.connectionRequestReceived"
    ]
  }
}

The wildcards are not listed: each namespace in this list, the part before the first ., can be selected as <namespace>.*.

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 }'

const { secret } = await admin.webhooks.setSigning({ id: "whs-...", signingEnabled: true });

from linkedapi import SetWebhookSigningParams

secret = admin.webhooks.set_signing(
    SetWebhookSigningParams(id="whs-...", signing_enabled=True)
).secret

linkedin admin webhook set-signing whs-... --on --json

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" }'

await admin.webhooks.setHeader({
  id: "whs-...",
  name: "Authorization",
  value: "Bearer your_endpoint_token",
});

from linkedapi import SetWebhookHeaderParams

admin.webhooks.set_header(
    SetWebhookHeaderParams(
        id="whs-...",
        name="Authorization",
        value="Bearer your_endpoint_token",
    )
)

printf 'Bearer %s' "$ENDPOINT_TOKEN" \
  | linkedin admin webhook set-header whs-... Authorization --value-stdin --json

linkedin admin webhook set-header <id> <name> --value-stdin
linkedin admin webhook set-header <id> <name> --value-env <variable>

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" }'

await admin.webhooks.deleteHeader({ id: "whs-...", name: "Authorization" });

from linkedapi import DeleteWebhookHeaderParams

admin.webhooks.delete_header(DeleteWebhookHeaderParams(id="whs-...", name="Authorization"))

linkedin admin webhook delete-header whs-... Authorization --json

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" } }'

await admin.webhooks.setHeaders({
  id: "whs-...",
  headers: { Authorization: "Bearer your_endpoint_token" },
});

from linkedapi import SetWebhookHeadersParams

admin.webhooks.set_headers(
    SetWebhookHeadersParams(
        id="whs-...",
        headers={"Authorization": "Bearer your_endpoint_token"},
    )
)

# headers.json: { "Authorization": "Bearer your_endpoint_token" }
cat headers.json | linkedin admin webhook set-headers whs-... --stdin --json

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-..." }'

const { secret } = await admin.webhooks.revealSecret({ id: "whs-..." });

from linkedapi import RevealWebhookSecretParams

secret = admin.webhooks.reveal_secret(RevealWebhookSecretParams(id="whs-...")).secret

linkedin admin webhook reveal-secret whs-... --print-secret
linkedin admin webhook reveal-secret whs-... --secret-file webhook-secret.txt

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-..." }'

const { secret } = await admin.webhooks.rotateSecret({ id: "whs-..." });

from linkedapi import RotateWebhookSecretParams

secret = admin.webhooks.rotate_secret(RotateWebhookSecretParams(id="whs-...")).secret

linkedin admin webhook rotate-secret whs-... --secret-file new-webhook-secret.txt

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-..." }'

await admin.webhooks.delete({ id: "whs-..." });

from linkedapi import DeleteWebhookParams

admin.webhooks.delete(DeleteWebhookParams(id="whs-..."))

linkedin admin webhook delete 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"

const deliveries = await admin.webhooks.deliveries();

deliveries = admin.webhooks.deliveries()

linkedin admin webhook deliveries --json

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-..." }'

await admin.webhooks.replayDelivery({ deliveryId: "whd-..." });

from linkedapi import ReplayWebhookDeliveryParams

admin.webhooks.replay_delivery(ReplayWebhookDeliveryParams(delivery_id="whd-..."))

linkedin admin webhook replay 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"

await admin.webhooks.sendTest();

admin.webhooks.send_test()

linkedin admin webhook send-test