> ## Documentation Index
> Fetch the complete documentation index at: https://doc.quippy-lab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a webhook endpoint

> Register a URL in the admin portal and capture its signing secret.

About **15 minutes**. You'll need a URL on your side that can accept
HTTPS `POST` requests with `Content-Type: application/json`, and a secret
manager to store the signing secret you'll receive.

<Note>
  Each institution can have up to **10 active webhook endpoints**. Hitting
  the limit is rare — if it matters to you, let us know.
</Note>

<Steps>
  <Step title="Open the Webhooks page">
    Sign in to [business.quippy-lab.com](https://business.quippy-lab.com), then
    open **Webhooks** from the sidebar. Click **+ Add endpoint**.

    <Frame>Admin portal — Webhooks list and "+ Add endpoint" button.</Frame>
  </Step>

  <Step title="Fill in the endpoint details">
    The **Add webhook endpoint** dialog has three fields.

    | Field                      | What to enter                                                                                              |
    | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
    | **Endpoint URL**           | The HTTPS URL Quippy will `POST` to, e.g. `https://your-app.com/hooks/quippy`. Must start with `https://`. |
    | **Description** (optional) | A human-readable label, e.g. `Production CRM integration`. Only you see this.                              |
    | **Events**                 | Tick the event types you want delivered to this endpoint. At least one is required.                        |

    <Note>
      The full list of event types, with sample payloads, is on the
      [Event catalog](/webhooks/events) page.
    </Note>

    Click **Create endpoint**.
  </Step>

  <Step title="Copy the signing secret — shown once">
    Immediately after creating the endpoint, Quippy shows the **signing
    secret** — a string starting with `whsec_`. It appears **once**.

    <Snippet file="secret-once-warning.mdx" />

    Copy the secret into your secret manager (AWS Secrets Manager, HashiCorp
    Vault, Doppler, 1Password, etc.) **before** closing the dialog. Your
    receiver will read it from there to verify signatures.

    If you lose the secret, you can rotate it on the endpoint's detail page
    — but any receiver using the old secret must be updated immediately or
    deliveries will start failing signature checks.
  </Step>

  <Step title="Send a test delivery">
    On the endpoint's detail page, click **Send test**. Quippy dispatches a
    synthetic `webhook.test` event to your URL. You should see:

    * A `200 OK` response from your endpoint (or whatever you returned) in
      the **Deliveries** log within a few seconds.
    * `X-Quippy-Event: webhook.test` on the request your server receives.

    If the test fails, see [Troubleshooting](/webhooks/troubleshooting). The
    most common cause is a missing or wrong signature check — see
    [Verify webhook signatures](/webhooks/verify-signature) next.
  </Step>
</Steps>

## Response requirements

Quippy treats a delivery as **successful** if your endpoint returns any
`2xx` status within the dispatcher's timeout. Anything else (4xx, 5xx,
timeout, connection refused) triggers the retry schedule — see
[Retries and delivery](/webhooks/retries).

<Warning>
  **Respond fast, do work async.** The dispatcher times out at **10 seconds**.
  Your endpoint should acknowledge the delivery (return `2xx`) and enqueue
  any real processing. Synchronous heavy work — database joins, LLM calls,
  downstream API calls — will blow past the timeout and force a retry.
</Warning>

## What's next

1. **Verify every delivery** — [Verify webhook signatures](/webhooks/verify-signature)
2. **Know the payloads** — [Event catalog](/webhooks/events)
3. **Understand retries** — [Retries and delivery](/webhooks/retries)