# Docs


- **Getting started**
- [Webhooks, delivered.](/docs): Everything you need to send signed webhooks, build a reliable receiver, and understand every delivery.
- [Send your first webhook](/docs/quickstart): From a new project to a confirmed delivery, one step at a time.

- **Build your integration**
- Core concepts
  - [Organizations and projects](/docs/concepts/projects): Understand the workspace that owns your endpoints, events, deliveries, and credentials.
  - [Events and idempotency](/docs/concepts/events): Publish business events safely and understand how they become deliveries.
  - [Deliveries, retries, and replay](/docs/concepts/deliveries): Follow a webhook from queueing through its attempts and final outcome.
- Receiver examples
  - [Build a receiver](/docs/receivers): Working Node.js and Bun receivers that verify signatures before accepting events.
  - [Node.js receiver](/docs/receivers/node): Start a signed webhook receiver with Node.js 22 or later.
  - [Bun receiver](/docs/receivers/bun): Start a signed webhook receiver with Bun 1.3 or later.
- Receiver security
  - [Verify webhook signatures](/docs/security/signatures): Authenticate the raw request body before accepting a webhook.
  - [Verify receiver ownership](/docs/security/verification): Complete the signed challenge before enabling an endpoint.
  - [Rotate signing secrets](/docs/security/rotation): Replace a receiver credential while accounting for the overlap period.

- **Project API**
- API reference
  - [Project API reference](/docs/api): Integrate your application using project-scoped endpoints, events, deliveries, and credentials.
  - [Authentication and project identity](/docs/api/authentication): Use a project API key and verify which project it authorizes.
  - [Errors, limits, and pagination](/docs/api/errors-pagination): Handle API problems and traverse resources without missing pages.
  - Project
    - [Read project status and credential project ID](/docs/api/project/get-project-status): Call before mutations and compare project_id with the selected project. Query parameters are rejected. A suspended project can be inspected but only an operator can resume it.
  - Endpoints
    - [Register a disabled endpoint](/docs/api/endpoints/create-endpoint): Registration does not perform a network request. Reuse matching endpoints before creating one; creation is not idempotent.
    - [Delete an endpoint](/docs/api/endpoints/delete-endpoint): Destructive. Requires explicit human approval.
    - [Read endpoint readiness and subscriptions](/docs/api/endpoints/get-endpoint)
    - [List endpoints](/docs/api/endpoints/list-endpoints): Returns newest-first retained data. Unknown or repeated query parameters are rejected. Follow next_cursor until null; preserve filters. Omit cursor on the first page.
    - [Provision or rotate a signing secret](/docs/api/endpoints/provision-or-rotate-signing-secret): EMPTY BODY required: do not send {}. Also rotates an existing secret; ask for explicit approval before rotation. Not idempotent. Previous secret has a five-minute grace period; overlapping rotation returns 409 signing_secret_rotation_in_progress. Does not disable an already active endpoint or clear verified_at. Inspect state after a lost response.
    - [Update endpoint configuration or enabled state](/docs/api/endpoints/update-endpoint): URL changes clear verification and disable delivery. Enabling requires verification and a signing secret. Replacing subscriptions changes future fan-out. Ask before modifying existing receiver configuration.
    - [Verify receiver ownership with a signed challenge](/docs/api/endpoints/verify-endpoint): EMPTY BODY required: do not send {}. Install the current secret on a running public HTTPS receiver first. Receiver must verify the raw signed request and return exactly {"proof":"<base64 HMAC-SHA256>"}, using message cascadehook.verify.v1.<Webhook-Id>.<data.challenge>. One attempt per 30 seconds; respect Retry-After. Plain empty 200 is insufficient. Errors include endpoint_verification_failed (502), invalid_verification_proof (422), unsafe_endpoint_destination (422), endpoint_verification_rate_limited (429), and endpoint_verification_changed (409).
  - Events
    - [Read an event including its original envelope](/docs/api/events/get-event)
    - [List event summaries](/docs/api/events/list-events): Returns newest-first retained data. Unknown or repeated query parameters are rejected. Follow next_cursor until null; preserve filters. Omit cursor on the first page.
    - [Publish an event](/docs/api/events/publish-event): Maximum 256 KiB envelope; exactly type and data. Same key/exact bytes within 24 hours returns the original receipt without fan-out again. Different bytes return 409 idempotency_conflict. Keys remain project-wide regardless of dev/live label; use only agreed test data.
  - Deliveries
    - [Read current delivery state](/docs/api/deliveries/get-delivery): succeeded confirms receiver acknowledgement, not downstream business completion. pending/leased are not terminal. Inspect attempts and terminal_reason for failures.
    - [List deliveries](/docs/api/deliveries/list-deliveries): Returns newest-first retained data. Unknown or repeated query parameters are rejected. Follow next_cursor until null; preserve filters. Omit cursor on the first page. To confirm a test, filter by BOTH the accepted event ID and the chosen endpoint ID. Poll at intervals of at least five seconds for at most 60 seconds; honor Retry-After.
    - [List completed delivery attempts](/docs/api/deliveries/list-delivery-attempts): Newest logical attempt first; cursor is bound to its delivery and cycle filter. Response bodies and sensitive headers are never exposed. Unknown or repeated query parameters are rejected.
    - [Replay a completed delivery](/docs/api/deliveries/replay-delivery): Explicit human approval required. Query parameters are rejected. Only succeeded/failed deliveries with a ready endpoint can be replayed. expected_cycle is the current delivery cycle. Same delivery/from-cycle returns its first receipt; stale cycle conflicts. Preserves Webhook-Id, so receiver deduplication may skip business work.
  - API keys
    - [Create a project API key](/docs/api/api-keys/create-api-key): Requires explicit human approval. Query parameters are rejected. dev/live labels grant the same project scope; neither is a sandbox or a restricted agent credential. Human setup should use the dashboard to obtain the initial key.
    - [Read API key metadata](/docs/api/api-keys/get-api-key): Query parameters are rejected. Does not return the complete credential.
    - [List API key metadata](/docs/api/api-keys/list-api-keys): Returns newest-first retained data. Unknown or repeated query parameters are rejected. Follow next_cursor until null; preserve filters. Omit cursor on the first page. Metadata excludes complete credentials.
    - [Revoke an API key](/docs/api/api-keys/revoke-api-key): EMPTY BODY, no query parameters. Requires explicit human approval. Cannot revoke the last usable key without a replacement.
    - [Rotate an API key](/docs/api/api-keys/rotate-api-key): EMPTY BODY, no query parameters. Requires explicit human approval. Existing replacement/inactive key conflicts; never rotate automatically on an ambiguous response.

- **Resources**
- [Support](/docs/support): Get help with Cascadehook integrations, deliveries, and account access.
- AI agent integration
  - [Set up with your AI agent](/docs/agents): Connect your application using your coding agent, project context, and a verifiable delivery.
  - [Agent integration protocol](/docs/agents/integration): The complete project API workflow for coding agents, from identity checks to a confirmed delivery.
- [Troubleshooting](/docs/troubleshooting): Find the next useful check when setup, publication, or delivery fails.