Skip to main content
skill CX Codex

lindy-webhooks-events — Claude Code skill: setup and use

The lindy-webhooks-events skill guides setup of Lindy AI webhook triggers and application callbacks. Use it to define event contracts, validate requests, and handle retries in a Lindy integration.

MIT 1 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lindy-webhooks-events -a claude-code
Open on GitHub

What lindy-webhooks-events does

The skill covers two separate flows: an application sends a request to Lindy’s Webhook Received trigger, and Lindy calls the application through an HTTP Request action. It guides you through closed payload schemas, trigger URL checks, and distinct secrets for each direction. A trigger secret must not go to a caller-provided callback address.

For retries, the instructions call for an atomic reservation of a stable request ID and durable queueing. Only transient outcomes should be retried, with bounded attempts. A timeout can leave the remote result unclear, so reconcile the request with Tasks or an authenticated callback. A 2xx response alone does not verify task completion.

The workflow also includes checks for payload size, malformed callbacks, duplicate events, and incorrect secrets. It requires a generated trigger secret, a separate application-owned callback secret, and an approved secret manager. Scaled or retryable processing needs a shared atomic idempotency store and a durable queue.

What it helps with

  • send application events to a Lindy trigger
  • validate a webhook URL before attaching its secret
  • authenticate Lindy callbacks with a separate application secret
  • deduplicate events before they cause repeated side effects
  • verify trigger results against tasks in Tasks

Example prompts for the agent

  • Set up an application event request to Lindy and validate the trigger URL and secret.
  • Design a Lindy callback receiver that checks its own secret and validates the payload schema.
  • Check event retries and reconcile the result with the task in Tasks.

How to install lindy-webhooks-events

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill lindy-webhooks-events -a claude-code

2Manually: put the files in place

~/.claude/skills/lindy-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/lindy-webhooks-events/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about lindy-webhooks-events

How do I install lindy-webhooks-events in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill lindy-webhooks-events -a claude-code. The skill file is available at ~/.claude/skills/lindy-webhooks-events/SKILL.md.

What does lindy-webhooks-events do?

It guides setup of Lindy webhook triggers and application callbacks, with checks for credentials, payload schemas, and duplicate requests.

Why does the callback need a separate secret?

The application callback must use its own secret rather than reusing the Lindy trigger credential. Authenticate the request before inspecting or acting on its body.

Source text

SKILL.md · MIT
---
name: lindy-webhooks-events
description: 'Configure Lindy AI webhook triggers, callback patterns, and event handling.

  Use when setting up webhook triggers, implementing callback receivers,

  or building event-driven Lindy integrations.

  Trigger with phrases like "lindy webhook", "lindy events",

  "lindy callback", "lindy webhook trigger".

  '
allowed-tools: Read, Write, Edit
version: 1.20.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lindy
- webhooks
compatibility: Compatible with AI coding agents that can read and edit application code and Markdown
---
# Lindy Webhooks and Events

## Overview

Build two documented boundaries: an application calls a Lindy **Webhook Received**
trigger using its generated Bearer secret, and Lindy calls an application through
an outbound callback action such as **HTTP Request**. Treat them as separate trust
directions with separate secrets, schemas, retry policies, and evidence.

Use **Read** to inspect the integration and **Write** or **Edit** to implement its
closed contracts. Implement only the documented generated-Bearer trigger and
configurable outbound-request surfaces; do not add unaudited control-plane,
registration, event-feed, or signature mechanisms.

## Prerequisites

- A Webhook Received trigger with its generated URL and nonempty generated secret.
- An approved secret manager; never store secret values in code or skill output.
- A separate, nonempty application-owned callback secret.
- A fixed or strictly allowlisted HTTPS callback destination controlled by the
  application owner.
- Closed request and callback schemas with local field, length, enum, and byte limits.
- A shared atomic idempotency store and durable queue for scaled or retryable work.
- Access to Lindy's Tasks view and synthetic test data with unique request IDs.

## Instructions

### Step 1: Define minimal contracts

Specify only fields the workflow needs. A safe application-owned trigger envelope
might contain `requestId`, an enumerated `eventType`, a non-sensitive `subjectId`,
and `occurredAt`. Reject unknown fields, invalid types, excessive lengths, and
payloads above the documented local byte limit before enqueue or transmission.

Define the callback separately—for example `requestId`, `taskId`, and an enumerated
`status`. Do not return full prompts, model output, source records, or customer data
unless an approved data contract requires those fields.

### Step 2: Configure the Lindy trigger

In the workflow, add **Webhook Received**, create or select a webhook, generate its
secret, and store that secret immediately. Lindy documents URLs in this form:

```text
https://public.lindy.ai/api/v1/webhooks/[unique-id]
```

Callers send `Authorization: Bearer [generated-secret]`. Select the documented
follow-up behavior that matches the workflow: handle in the same task, create a new
task, or ignore follow-ups. Treat request body, headers, and query parameters as
untrusted input. Never copy the full headers object into a prompt or log because it
can contain the Authorization secret.

### Step 3: Validate before attaching the trigger secret

Fail startup unless the URL uses HTTPS, has hostname exactly `public.lindy.ai`, no
unexpected port or embedded credentials, and the expected generated webhook path.
Load a nonempty per-trigger secret only after the destination passes validation.

```typescript
type TriggerConfig = { url: URL; secret: string };

function loadTriggerConfig(env: NodeJS.ProcessEnv): TriggerConfig {
  const url = new URL(env.LINDY_TRIGGER_URL ?? '');
  const path = url.pathname.split('/').filter(Boolean);
  if (
    url.protocol !== 'https:' ||
    url.hostname !== 'public.lindy.ai' ||
    url.port !== '' ||
    url.username !== '' ||
    url.password !== '' ||
    url.search !== '' ||
    url.hash !== '' ||
    path.length !== 4 ||
    path[0] !== 'api' ||
    path[1] !== 'v1' ||
    path[2] !== 'webhooks' ||
    path[3].length === 0
  ) {
    throw new Error('LINDY_TRIGGER_URL is not an approved Lindy webhook URL');
  }

  const secret = env.LINDY_TRIGGER_SECRET ?? '';
  if (secret.length === 0) throw new Error('LINDY_TRIGGER_SECRET is required');
  return { url, secret };
}
```

Do not send the trigger secret to a caller-supplied `callbackUrl`, another Lindy
host, or your own callback receiver.

### Step 4: Deduplicate, queue, and send

Require a stable request ID derived from the source business event. Atomically
reserve that ID and durably enqueue the validated event. A process-local set,
background promise, or timer is not durable and does not coordinate across instances.

The worker sends the closed payload with the generated Bearer secret. Treat 2xx as
transport acceptance only. Treat authentication and other non-retryable 4xx as
permanent failures. Retry only explicitly transient outcomes such as 408, 429, or
selected 5xx with capped exponential backoff, jitter, bounded attempts, and a total
deadline. Reuse the same request ID; dead-letter and alert after exhaustion.

An ambiguous timeout may occur after Lindy accepted the request. Local idempotency
cannot prove exactly-once remote execution, so reconcile the request ID with the
Tasks view or an authenticated callback before retrying or claiming completion.

### Step 5: Configure a distinct authenticated callback

Prefer an application-owned, pre-approved HTTPS callback URL. Configure a Lindy
HTTP Request action to send the closed callback body and:

```text
Authorization: Bearer [application-owned-callback-secret]
Content-Type: application/json
```

The HTTP Request action documentation supports explicit headers and status-code
handling. If using a callback URL from the trigger body, validate it against an
exact scheme/host/path allowlist before any secret-bearing request. If the chosen
callback action cannot enforce that validation and the required Authorization
header, do not use a caller-controlled URL.

At the application receiver, authenticate before inspecting or acting on the body,
enforce a request-byte limit before parsing, validate the closed schema, and use an
atomic `enqueueOnce(requestId, payload)` operation. Return 2xx only after durable
persistence succeeds. Use constant-time secret comparison and never reuse the
Lindy trigger secret as the callback secret.

### Step 6: Corroborate tasks and callbacks

For a synthetic trigger, record its unique request ID and transport result, then
find the corresponding task in Lindy's Tasks view and verify the intended steps and
terminal state. A 2xx trigger response without a matching task is
`ACCEPTED_UNVERIFIED`, not success.

Test a wrong trigger secret: require non-2xx and no task. Test a wrong callback
secret, malformed and oversized callbacks, duplicates, durable-store failure, and
worker termination after enqueue: each must create no unauthorized or duplicate
side effect.

### Step 7: Minimize evidence and telemetry

Record request ID, task ID, status class, attempt, latency, queue disposition, and
sanitized workflow identifier. Do not log secrets, full generated webhook URLs,
headers, full request/response bodies, prompts, model output, or customer content.

See [the implementation guide](references/implementation-guide.md) for bounded
sender and receiver patterns plus the qualification matrix.

## Output

Produce an integration record containing:

- closed trigger and callback schemas with local byte limits;
- exact trigger destination-validation rules and secret-manager references;
- distinct trigger and callback authentication boundaries;
- shared idempotency, durable queue, retry, dead-letter, and reconciliation policy;
- callback allowlist and durable acknowledgement contract;
- synthetic positive, negative-auth, malformed, duplicate, retry, and restart receipts;
- Tasks-view correlation and sanitized destination evidence; and
- final `VERIFIED`, `FAILED`, or `NOT VERIFIED` disposition with owners.

## Examples

### Minimal verified flow

```text
source event
  -> closed schema
  -> shared idempotency + durable queue
  -> exact public.lindy.ai HTTPS trigger + generated Bearer secret
  -> Lindy task correlated by requestId
  -> fixed application callback + distinct Bearer secret
  -> authenticated validation + durable enqueueOnce
  -> terminal outcome ledger
```

### Correct handling of a 2xx response

If the trigger returns 2xx but no matching task can be found, record
`ACCEPTED_UNVERIFIED`, keep the event reconcilable, and investigate. Do not mark the
business operation complete or send a blind sequence of retries.

## Error Handling

| Failure | Required response |
|---|---|
| Trigger URL fails exact sink validation | Refuse to construct the secret-bearing request |
| Generated trigger secret is empty | Fail startup or configuration validation |
| Trigger payload is malformed or excessive | Reject before claim, enqueue, or send |
| 401/403 or permanent 4xx | Stop retries, redact telemetry, alert owner |
| 408/429/selected 5xx | Apply bounded retry; dead-letter after exhaustion |
| Ambiguous timeout | Reconcile stable request ID; do not claim exactly-once delivery |
| Callback target is caller-controlled or not allowlisted | Do not attach callback secret |
| Callback auth/schema fails | Return non-2xx and create no durable job |
| Durable enqueue fails | Return non-2xx; never acknowledge unpersisted work |
| 2xx without a matching task | Mark `ACCEPTED_UNVERIFIED` and investigate |

## Resources

- [Lindy Webhooks](https://docs.lindy.ai/skills/by-lindy/webhooks)
- [Lindy HTTP Request](https://docs.lindy.ai/skills/by-lindy/http-request)
- [Lindy Tasks](https://docs.lindy.ai/fundamentals/lindy-101/tasks)
- [Lindy Test Panel](https://docs.lindy.ai/testing/test-panel)
- [Detailed sender, receiver, and test patterns](references/implementation-guide.md)

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
backlog-grooming-assistant backlog-grooming-assistant automates backlog grooming workflows, guides task refinement, and validates project management configurations. CX Codex +1 1installs long-polling-handler An auto-activating skill for long polling handler work in API integrations, with step-by-step guidance, generated code and configuration checks. CX Codex +1 1installs emitting-api-events emitting-api-events — a skill that builds event-driven APIs: outbound webhooks, Server-Sent Events, and message broker integration. Fits projects where mutations need to notify downstream services. CX Codex +1 1installs maintainx-webhooks-events maintainx-webhooks-events configures MaintainX webhook ingestion and work order event handlers in Express. Useful when connecting maintenance status changes to external systems. CX Codex +1 1installs fireflies-webhooks-events fireflies-webhooks-events walks an agent through building a Fireflies Webhooks V2 receiver: raw-body HMAC check, event allowlisting, dedupe, and a 2xx reply fast enough for the 10-second window. CX Codex +1 1installs documenso-webhooks-events documenso-webhooks-events configures Documenso webhook endpoints and event handlers. Useful when tracking document signing status and automating downstream actions. CX Codex +1 1installs windsurf-webhooks-events The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output. CX Codex +1 1installs twinmind-webhooks-events twinmind-webhooks-events — a skill for TwinMind meeting events: transcription completion, action item extraction, and calendar sync notifications. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open