# Webhook

The Webhook block sends HTTP POST requests to external webhook endpoints with automatic webhook headers and optional HMAC signing.

![Webhook Block](https://docs.steelengine.com/static/blocks/webhook.png)

## Configuration

### Webhook URL

The destination endpoint for your webhook request. Supports both static URLs and dynamic values from other blocks.

### Payload

JSON data to send in the request body. Use the AI wand to generate payloads or reference workflow variables:

```json
{
  "event": "workflow.completed",
  "data": {
    "result": "<agent.content>",
    "timestamp": "<function.result>"
  }
}
```

### Signing Secret

Optional secret for HMAC-SHA256 payload signing. When provided, adds an `X-Webhook-Signature` header:

```
X-Webhook-Signature: t=1704067200000,v1=5d41402abc4b2a76b9719d911017c592...
```

To verify signatures, compute `HMAC-SHA256(secret, "${timestamp}.${body}")` and compare with the `v1` value.

### Additional Headers

Custom key-value headers to include with the request. These override any automatic headers with the same name.

### Delivery Mode

**Wait for response** is the default. The block waits for the endpoint and exposes its response body, HTTP status, and headers to downstream blocks.

**Fire and forget (best effort)** validates the URL and payload, then starts delivery in the background. The workflow continues with `dispatched: true`. This confirms that the request was validated and scheduled, not that the endpoint received it. Invalid requests and exhausted background capacity fail the block before dispatch:

* The URL must be an absolute `http://` or `https://` URL. Anything else fails with `Fire-and-forget requires an absolute HTTP(S) URL`.
* Each worker keeps at most 32 background requests in flight. When that capacity is full the block fails with `Background webhook capacity reached; retry later or use Wait for response`.

Background delivery can be lost if the worker shuts down. Attempts have a 30-second deadline and a 64 KiB response limit. Later delivery failures are logged but do not fail or retry the completed block. Choose Wait for response when delivery results matter or downstream blocks need the response.

## Automatic Headers

Every request includes these headers automatically:

| Header                | Description                               |
| --------------------- | ----------------------------------------- |
| `Content-Type`        | `application/json`                        |
| `X-Webhook-Timestamp` | Unix timestamp in milliseconds            |
| `X-Delivery-ID`       | Unique UUID for this delivery             |
| `Idempotency-Key`     | Same as `X-Delivery-ID` for deduplication |

## Outputs

| Output       | Type    | Description                                                               |
| ------------ | ------- | ------------------------------------------------------------------------- |
| `data`       | json    | Response body; only available in Wait for response mode                   |
| `status`     | number  | HTTP status code; only available in Wait for response mode                |
| `headers`    | object  | Response headers; only available in Wait for response mode                |
| `dispatched` | boolean | Only available in Fire and forget mode. Confirms scheduling, not delivery |

## Example Use Cases

**Notify external services** - Send workflow results to Slack, Discord, or custom endpoints

```
Agent → Function (format) → Webhook (notify)
```

**Trigger external workflows** - Start processes in other systems when conditions are met

```
Condition (check) → Webhook (trigger) → Response
```

The Webhook block always uses POST. For other HTTP methods or more control, use the [API block](/blocks/api).

## Common Questions

**Can I use HTTP methods other than POST?**

No. The Webhook block always sends POST requests. If you need GET, PUT, DELETE, or PATCH, use the API block instead, which supports all standard HTTP methods.

**How does HMAC payload signing work?**

When you provide a signing secret, the block generates an HMAC-SHA256 signature of the payload and includes it in the X-Webhook-Signature header in the format t=timestamp,v1=signature. The receiver can verify by computing HMAC-SHA256(secret, "timestamp.body") and comparing with the v1 value.

**What headers are added automatically?**

Every webhook request automatically includes Content-Type (application/json), X-Webhook-Timestamp (Unix timestamp in milliseconds), X-Delivery-ID (unique UUID), and Idempotency-Key (same as X-Delivery-ID for deduplication).

**Can custom headers override the automatic ones?**

Yes. Any custom headers you define in the Additional Headers section will override automatic headers that share the same name.

**How is the Webhook block different from the API block?**

The Webhook block is purpose-built for webhook delivery: it is POST-only, automatically adds webhook-specific headers (timestamp, delivery ID, idempotency key), and supports optional HMAC signing. The API block is more general-purpose with support for all HTTP methods, query parameters, and configurable retries.
