> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortado.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Register endpoints so workflows can send signed events to Zapier, n8n, or your own systems

## Webhooks Overview

Webhooks let Cortado notify another system the moment a workflow step runs — a new lead, a quote that was just sent, a payment that cleared. You register a URL under **Settings > Integrations > Webhooks**, then add a **Send webhook** step to any workflow.

Webhooks are part of [Workflows](/guides/workflows). If you don't see the Webhooks section, workflows aren't enabled for your organization yet.

## Register an Endpoint

<Steps>
  <Step title="Open Webhooks">
    Go to **Settings > Integrations > Webhooks** and click **Add endpoint**.
  </Step>

  <Step title="Name it and paste a URL">
    Use a name that says where it goes (`Zapier — new leads`, `n8n payment alert`). The URL must be a public **https** address — local or private hosts are rejected.
  </Step>

  <Step title="Optional headers">
    Add any extra headers your receiver needs, such as an API key. Cortado reserves its own `X-Cortado-*` headers, so you can't set those yourself.
  </Step>

  <Step title="Copy the signing secret">
    Cortado shows the secret once, prefixed with `whsec_`. Store it in your automation tool. You won't see it again unless you rotate it.
  </Step>
</Steps>

<Warning>
  Treat the signing secret like a password. Anyone who has it can forge deliveries that look like they came from Cortado. Rotate it if it may have leaked.
</Warning>

## What Gets Sent

Each delivery is a signed JSON POST. The body includes:

* **event** — what happened (for example a lead stage change), `manual` if you ran the workflow yourself, or `webhook.test` for a test ping
* **data type and id** — the record the workflow is acting on
* **timestamps** — when the trigger happened and when this delivery was sent
* **trigger payload** — the details from the workflow trigger

Cortado also sends headers your receiver can use to verify and dedupe:

* `X-Cortado-Signature` — timestamped signature of the body
* `X-Cortado-Event` — the event type
* `X-Cortado-Delivery` — a stable id, the same on every retry of that step
* `X-Cortado-Timestamp` — when this attempt was signed

<Tip>
  Have your receiver check `X-Cortado-Signature` before trusting the body, and ignore a delivery you've already processed with the same `X-Cortado-Delivery` id.
</Tip>

## Test, Disable, and Rotate

From the endpoints table you can:

* **Send test** — Cortado posts a `webhook.test` event immediately so you can confirm the URL and signature check work
* **Enable / disable** — a disabled endpoint stays in the list but workflows that target it fail until you turn it back on
* **Rotate secret** — issues a new `whsec_` secret (shown once) and invalidates the old one
* **Delete** — remove an endpoint you no longer use. Cortado blocks delete while a workflow still points at it

## Add a Send Webhook Step

Once at least one endpoint exists:

1. Open **Workflows** and edit a workflow (or start from a template).
2. Add a **Send webhook** step from the palette.
3. Choose the endpoint. The URL and secret stay on the endpoint — the step only picks which one to call.

Failed deliveries are retried. If the other system rejects the request (most 4xx responses), that step fails and the run stops.

See the [Workflows guide](/guides/workflows) for triggers, other steps, and how to watch runs.

## Best Practices

1. **Use one endpoint per tool** — if you rotate or disable Zapier, n8n keeps working
2. **Copy the secret immediately** — it's shown once on create and on rotate
3. **Send a test before you turn the workflow on** — confirm the URL and signature check first
4. **Keep the URL on https** — Cortado won't deliver to http or private hosts
5. **Dedupe on the delivery id** — retries reuse the same `X-Cortado-Delivery` so your tool shouldn't create a second task
6. **Disable instead of deleting** while you debug — workflows that still reference a deleted endpoint can't be saved

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/guides/workflows">
    Build the automations that fire your webhooks.
  </Card>

  <Card title="API Keys" icon="key" href="/guides/integrations/api-keys">
    Pull leads and contacts from your own tools.
  </Card>

  <Card title="Settings" icon="gear" href="/guides/settings">
    Where Integrations and Webhooks live.
  </Card>

  <Card title="Staff" icon="users" href="/guides/staff">
    Who can manage settings and automations.
  </Card>
</CardGroup>