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

# Getting started with webhooks

> Receive real-time transaction notifications instead of polling the API.

Webhooks push notifications to your endpoint as events happen, so you do not have to poll for
updates. Because charges and payouts settle asynchronously, webhooks are the primary way you learn
that money actually moved.

## Set up a webhook

<Steps>
  <Step title="Log in to your dashboard">
    Go to [app.zerocash.tech](https://app.zerocash.tech).
  </Step>

  <Step title="Open Webhooks">
    Find the **Webhooks** section in the sidebar.
  </Step>

  <Step title="Add your URL">
    Register an HTTPS endpoint. Sandbox and production are configured separately.
  </Step>

  <Step title="Verify signatures">
    Before trusting any payload, check the signature. See
    [Webhook secrets](/guides/webhooks/secrets).
  </Step>
</Steps>

<Info>
  You can read back your currently configured webhook URLs for both environments through
  [Get User](/api-reference/endpoint/get-user).
</Info>

## Delivery behaviour

|             | Behaviour                                                                            |
| :---------- | :----------------------------------------------------------------------------------- |
| **Timeout** | If your server does not respond within **15 seconds**, the attempt is marked failed. |
| **Retries** | Failed webhooks are retried up to **3 times** with exponential backoff.              |
| **Backoff** | 1st retry after 5s · 2nd after 15s · 3rd after 45s                                   |

<Warning>
  Keep your handler lightweight. Acknowledge with a `2xx` immediately and offload database writes,
  notifications, and other slow work to a background job. Doing that work inline is the usual
  cause of the 15-second timeout — and a timeout means a retry, which means you may process the
  same event twice.
</Warning>

## Writing a reliable handler

<AccordionGroup>
  <Accordion title="Respond fast, process later" icon="bolt">
    Validate the signature, enqueue the payload, return `200`. Anything else belongs in a worker.

    ```javascript theme={null}
    app.post("/webhooks/zerocash", (req, res) => {
      if (!isValidSignature(req)) return res.status(401).end();

      queue.push(req.body);   // hand off
      res.status(200).end();  // acknowledge within 15s
    });
    ```
  </Accordion>

  <Accordion title="Make processing idempotent" icon="fingerprint">
    Retries mean the same event can arrive more than once, and events can arrive out of order. Key
    your processing on `transactionId` (or your `externalReference`) and ignore an event that would
    move a transaction backwards from a terminal state.
  </Accordion>

  <Accordion title="Never trust the payload alone for high-value actions" icon="shield-check">
    For anything irreversible, confirm against
    [Get Transaction](/api-reference/endpoint/get-transaction) before releasing value.
  </Accordion>

  <Accordion title="Return 2xx even for events you ignore" icon="check">
    A non-2xx tells Zerocash the delivery failed and triggers a retry. If you receive an event type
    you do not handle, acknowledge it anyway.
  </Accordion>
</AccordionGroup>

## Inspecting and replaying deliveries

| Task                        | Endpoint                                                     |
| :-------------------------- | :----------------------------------------------------------- |
| List delivery attempts      | [Get Webhooks](/api-reference/endpoint/get-webhooks)         |
| Inspect one delivery        | [Get Webhook](/api-reference/endpoint/get-webhook)           |
| Retry a delivery            | [Resend Webhook](/api-reference/endpoint/resend-webhook)     |
| Fire a test event (sandbox) | [Simulate Webhook](/api-reference/endpoint/simulate-webhook) |

<Tip>
  Simulate Webhook lets you exercise your handler against every event shape without running real
  transactions — useful for testing failure paths that are hard to trigger on demand.
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Webhook secrets" icon="key" href="/guides/webhooks/secrets">
    Verify that a request genuinely came from Zerocash.
  </Card>

  <Card title="Event types & structures" icon="code" href="/guides/webhooks/event-types">
    The base envelope, event names, and transaction types.
  </Card>
</CardGroup>