Webhook Lifecycle with the Clay CLI

clay webhooks creates, tests, lists, and deletes webhook endpoints that Clay signs deliveries to. The signing secret is returned exactly once, at creation, and test reports the real HTTP status the endpoint returned rather than a simple pass/fail.

What you will build

A full create-test-delete cycle against a real endpoint, showing the one-time secret and a real delivery failure status.

clay webhooks create <url>    (signingSecret returned once)
    ↓
clay webhooks test <id>       (real delivery attempt, real status code)
    ↓
clay webhooks delete <id>

AI Prompt

Using the Clay CLI, create a webhook, send it a signed test event, and delete it.

Requirements:
- `clay webhooks create <url>` returns { id, url, createdAt, signingSecret }. Capture
  signingSecret immediately: it is never returned again by list or get.
- `clay webhooks test <id>` sends a real signed event to the endpoint and reports
  { id, status: "delivered"|"failed", statusCode }, reflecting the endpoint's actual HTTP
  response rather than only whether the request was sent.
- `clay webhooks list` never includes signingSecret, by design.
- Clean up with `clay webhooks delete <id>` once done.
- Run the verification step below before finishing.

Using the Clay CLI, create a webhook, send it a signed test event, and delete it.

Requirements:
- `clay webhooks create <url>` returns { id, url, createdAt, signingSecret }. Capture
  signingSecret immediately: it is never returned again by list or get.
- `clay webhooks test <id>` sends a real signed event to the endpoint and reports
  { id, status: "delivered"|"failed", statusCode }, reflecting the endpoint's actual HTTP
  response rather than only whether the request was sent.
- `clay webhooks list` never includes signingSecret, by design.
- Clean up with `clay webhooks delete <id>` once done.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
An HTTPS URL to receive the test delivery (any reachable endpoint works for the test call itself)

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Create the webhook

clay webhooks create https://example.com/hooks/clay

clay webhooks create https://example.com/hooks/clay

Real output:

{
  "id": "wh_example",
  "url": "https://example.com/hooks/clay",
  "createdAt": "2026-09-28T23:07:58.395Z",
  "signingSecret": "whsec_<redacted>"
}

{
  "id": "wh_example",
  "url": "https://example.com/hooks/clay",
  "createdAt": "2026-09-28T23:07:58.395Z",
  "signingSecret": "whsec_<redacted>"
}

signingSecret only ever appears in this create response. There is no command to retrieve it later.

2. Send a test delivery

clay webhooks test wh_example

clay webhooks test wh_example

Real output, against an endpoint that does not accept the request:

{ "id": "wh_example", "status": "failed", "statusCode": 405 }

{ "id": "wh_example", "status": "failed", "statusCode": 405 }

statusCode is the endpoint's own real HTTP response code, here a 405 because the test target did not accept the delivery method. A working receiver returns status: "delivered" with its own 2xx code instead.

3. Delete the webhook

clay webhooks delete wh_example

clay webhooks delete wh_example

Real output:

{ "ok": true }

{ "ok": true }

Verify the result

clay webhooks list

clay webhooks list

Expected: the deleted webhook's id no longer appears, and no list or get-style response for any webhook ever includes signingSecret.

How it works

test is a real delivery, not a local validation of the URL's shape: it exercises the same signing and delivery path a live event would use, and reports back whatever HTTP status the receiving endpoint actually returned. This makes test useful for confirming a receiver is reachable and correctly configured before wiring it into a signal or workflow's real event traffic, rather than only confirming the webhook record itself was created.

Common issues

Losing the signing secret

Because signingSecret is shown only in the create response, a caller that does not capture it immediately has no way to retrieve it afterward; the only recovery is deleting the webhook and creating a new one, which issues a new secret.

A `failed` test status is a real endpoint response, not a Clay-side error

A 405, 404, or other non-2xx statusCode on test means the receiving endpoint rejected or mishandled the delivery, which is information about the receiver, not about the webhook record itself. The webhook still exists and is still usable once the receiver is fixed.

Next steps

GTM Agent Schedules with the Clay CLI

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay webhooks test <id>"
  expected_result: "Returns the receiving endpoint's real HTTP status under statusCode, with status 'delivered' only on a 2xx response."

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay webhooks test <id>"
  expected_result: "Returns the receiving endpoint's real HTTP status under statusCode, with status 'delivered' only on a 2xx response."