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

# Trigger webhook

> POST https://trigger.paddock.build/{id}: the endpoint other services post events to, and how it answers.

```http theme={null}
POST https://trigger.paddock.build/{id}
Content-Type: application/json
```

The URL of a [trigger](https://docs.paddock.build/guides/triggers.md), as `trigger.url` returns it. Any service posts JSON events to it. It takes no API key: the URL is unguessable, and a trigger with verification requires an HMAC-SHA256 signature of the body with the trigger's secret.

| Part | Rule |
| - | - |
| Method | `POST` only |
| `{id}` | The trigger's ID, `trg_...` |
| Body | JSON, at most 1 MiB. The `Content-Type` is not checked, but the body must be JSON: set GitHub's webhook content type to `application/json`, since its form encoding is not JSON |
| Headers and query | Available to the trigger's filters and templates as `headers` (names in lowercase) and `query` |
| Signature | When the trigger verifies: the trigger's `verification.header` holding `verification.prefix` and the lowercase hex HMAC-SHA256 of the raw body |
| CORS | None; the endpoint is for servers |

## Answers

paddock answers in this order and records a delivery for every request to an existing trigger. A `2xx` answer means the delivery is stored; the rules' work happens after it.

| Step | When | Answer | Recorded |
| - | - | - | - |
| 1. Find the trigger | Unknown or deleted | `404 not_found`, `details.resource: "trigger"` | Nothing |
| 2. Read the body | Over 1 MiB | `413 payload_too_large`, `details.reason: "invalid_body"` | A rejected delivery, without the body |
| 3. Verify the signature | Missing or wrong | `401 unauthorized`, `details.reason: "bad_signature"` | A rejected delivery |
| 4. Parse the body | Not JSON | `400 invalid_request`, `details.reason: "invalid_body"` | A rejected delivery |
| 5. Deduplicate | Same dedupe key as a recorded delivery | `200` with `{ "deliveryId", "duplicate": true }`, naming the first delivery | Nothing new |
| 6. Run the rules and store | Storage briefly unavailable | `503 unavailable` | Nothing; the sender may retry |
| 7. Accept | Otherwise | `202` with `{ "deliveryId" }` | A delivery, `pending` or already `done` |

A rejected request's error body names the delivery recorded for it in `details.deliveryId`, so you can find it in the trigger's deliveries.

```json 202 Accepted theme={null}
{ "deliveryId": "dlv_01h455vb4pex5vsknk084sn02q" }
```

```json 200 OK (duplicate) theme={null}
{ "deliveryId": "dlv_01h455vb4pex5vsknk084sn02q", "duplicate": true }
```

```json 401 Unauthorized theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "the signature in X-Hub-Signature-256 is missing or wrong",
    "details": { "reason": "bad_signature", "deliveryId": "dlv_01h455vb4pex5vsknk084sn03r" }
  }
}
```

The answer never says what the rules or the agents will do: those are the delivery's outcomes, which you read with `trigger.deliveries.get(deliveryId)` or in the console.

## Try it

```bash theme={null}
curl -X POST "$TRIGGER_URL" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: ping" \
  -d '{"zen": "Keep it logically awesome."}'
```

For a trigger that verifies signatures, sign the exact bytes you send:

```bash theme={null}
body='{"action":"opened"}'
signature="sha256=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
curl -X POST "$TRIGGER_URL" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $signature" \
  -d "$body"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.