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

# Mock Webhooks

> Configure outbound HTTP callbacks that GoDizzy fires after serving a mock response, so your agent or downstream system receives realistic webhook events.

Many real APIs do not just respond to your request — they also send a webhook to notify your system of something that happened asynchronously. Payment confirmations, job completions, and status change notifications are common examples. **Mock webhooks** let you simulate those outbound callbacks so you can test your webhook handler without a live upstream.

When a mock rule matches an incoming request, GoDizzy serves the mock response immediately, then fires your configured webhooks in the background — one after another, in the order you define them.

## How mock webhooks work

Each mock rule has an ordered list of webhook callbacks. After GoDizzy returns the mock response to the caller:

1. GoDizzy processes the webhook list from top to bottom.
2. For each webhook, it waits the configured **delay** (in milliseconds), then sends the HTTP request.
3. Each webhook is delivered independently. A failed webhook does not block subsequent ones.

Delivery runs asynchronously on durable infrastructure — the webhooks are enqueued at response time and retried at the platform level if the initial attempt fails.

<Warning>
  Webhook delivery is **asynchronous**. Your caller receives the mock response before any webhooks are dispatched. Do not rely on webhook delivery completing within a specific wall-clock window relative to the mock response.
</Warning>

## Configure webhooks on a mock rule

<Steps>
  <Step title="Open the mock rule editor">
    Navigate to your route collection, open the routing rule you want to attach webhooks to, and ensure the action is set to **Mock**.
  </Step>

  <Step title="Add a webhook">
    In the **Webhooks** section of the rule editor, click **Add Webhook**. Each webhook has the following fields:

    | Field          | Description                                                                        |
    | -------------- | ---------------------------------------------------------------------------------- |
    | **URL**        | The endpoint GoDizzy will POST to. Must be on an allowlisted domain.               |
    | **Method**     | The HTTP method (e.g., `POST`, `PUT`).                                             |
    | **Headers**    | A JSON object of request headers to include with the callback. Supports templates. |
    | **Body**       | The payload to send. Supports templates referencing the incoming request body.     |
    | **Delay (ms)** | How long GoDizzy waits before sending this specific webhook, in milliseconds.      |
  </Step>

  <Step title="Set the delay">
    The delay is per-webhook, not global. Use it to simulate the realistic gap between your mock response and the callback a real API would send. For a payment processor that typically calls back within 2–5 seconds, set the delay to somewhere in that range.
  </Step>

  <Step title="Add more webhooks (optional)">
    Click **Add Webhook** again to add a second callback. GoDizzy fires them in the order listed. You can reorder them by dragging.
  </Step>

  <Step title="Save the rule">
    Click **Save**. Webhooks take effect immediately for all subsequent requests that match this rule.
  </Step>
</Steps>

## URL allowlisting

GoDizzy only sends outbound webhook requests to URLs on your organization's allowlist. This prevents accidental callbacks to external production systems and limits the blast radius of a misconfigured rule.

If you attempt to save a webhook URL that is not allowlisted, GoDizzy will reject the configuration with a validation error.

<Tip>
  Add your local development server, your staging webhook receiver, or your internal test endpoint to the allowlist before configuring webhooks. Contact your organization admin or check your account settings to manage the allowlist.
</Tip>

## Template variables in webhooks

Webhook **headers** and **body** support the same template variables as mock response bodies. You can also reference top-level fields from the incoming request body using `{{$reqBody['key']}}`.

| Syntax                       | Available in  | Description                                         |
| ---------------------------- | ------------- | --------------------------------------------------- |
| `{{$randomUUID}}`            | Body, headers | New UUID per delivery                               |
| `{{$isoTimestamp}}`          | Body, headers | UTC timestamp at delivery time                      |
| `{{$unixSeconds}}`           | Body, headers | Unix epoch seconds                                  |
| `{{$unixMs}}`                | Body, headers | Unix epoch milliseconds                             |
| `{{$date}}`                  | Body, headers | `YYYY-MM-DD` in UTC                                 |
| `{{$randomInt(a,b)}}`        | Body, headers | Random integer in range                             |
| `{{$randomAlphaNumeric(n)}}` | Body, headers | Random alphanumeric string                          |
| `{{$randomHex(n)}}`          | Body, headers | Random hex string                                   |
| `{{$reqBody['key']}}`        | Body only     | Top-level field from the incoming request JSON body |

## Example: simulate a payment webhook

Your agent calls `POST /payments` to initiate a payment. In production, the payment processor calls your webhook at `https://your-service.example.com/webhooks/payments` a few seconds later with a `payment.completed` event.

**Mock rule configuration:**

* Method: `POST`
* Path: `/payments`
* Status: `200`
* Body:
  ```json theme={null}
  {
    "payment_id": "{{$randomUUID}}",
    "status": "processing",
    "created_at": "{{$isoTimestamp}}"
  }
  ```

**Webhook configuration:**

* URL: `https://your-service.example.com/webhooks/payments`
* Method: `POST`
* Delay: `3000` ms (simulates the processor's 3-second processing time)
* Headers:
  ```json theme={null}
  {
    "Content-Type": "application/json",
    "X-Webhook-Id": "{{$randomUUID}}",
    "X-Delivery-Timestamp": "{{$unixMs}}"
  }
  ```
* Body:
  ```json theme={null}
  {
    "event": "payment.completed",
    "payment_id": {{$reqBody['payment_id']}},
    "amount": {{$reqBody['amount']}},
    "currency": {{$reqBody['currency']}},
    "status": "succeeded",
    "completed_at": "{{$isoTimestamp}}",
    "idempotency_key": "{{$randomUUID}}"
  }
  ```

When your agent posts to the mock rule, it receives the `200 processing` response immediately. Three seconds later, your webhook handler receives the `payment.completed` event — with fields echoed from the original request — exactly as it would from the real payment processor.

## Example: simulate a multi-step job pipeline

Some APIs fire multiple webhooks as a job moves through stages. Use an ordered list of webhooks with increasing delays:

| # | URL                                              | Delay     | Event           |
| - | ------------------------------------------------ | --------- | --------------- |
| 1 | `https://your-service.example.com/webhooks/jobs` | `1000` ms | `job.queued`    |
| 2 | `https://your-service.example.com/webhooks/jobs` | `4000` ms | `job.running`   |
| 3 | `https://your-service.example.com/webhooks/jobs` | `9000` ms | `job.completed` |

GoDizzy fires each one after its configured delay, giving your handler a realistic sequence of state transitions to process.