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

# Webhooks and monitoring

> Set up webhooks and monitoring for your Prequel Import data pipelines

Prequel Import emits webhooks for a number of event types. You can subscribe to specific event types and configure delivery through HTTPS, Slack, PagerDuty, or Datadog using the `/webhooks` endpoints.

## Managing webhook subscriptions

The webhook subscription API supports full CRUD:

| Method   | Path                     | Purpose                                 |
| -------- | ------------------------ | --------------------------------------- |
| `GET`    | `/webhooks`              | List webhook subscriptions.             |
| `POST`   | `/webhooks`              | Create a webhook subscription.          |
| `GET`    | `/webhooks/{webhook_id}` | Retrieve a single webhook subscription. |
| `PATCH`  | `/webhooks/{webhook_id}` | Update a webhook subscription.          |
| `DELETE` | `/webhooks/{webhook_id}` | Delete a webhook subscription.          |

Each webhook subscription targets exactly one delivery vendor. The request body uses a `webhook` wrapper containing vendor-specific options.

## Webhook event types

Prequel Import webhook event types are in flux and are expected to change. They will be documented here soon.

## Delivery methods

### HTTP POST and GET

Prequel Import supports HTTPS callbacks to your webhook receiver. When creating a webhook with `vendor: generic_post`, payloads arrive as JSON. The `vendor: generic_get` type delivers payloads as URL parameters. Both require a `url` and accept an optional `api_key` for authenticated receivers.

### Third-party integrations

You can route events to PagerDuty (`vendor: pagerduty`), Slack (`vendor: slack`), and Datadog (`vendor: datadog`) with vendor-specific payload formatting. Slack expects a `https://hooks.slack.com/services/...` URL. PagerDuty and Datadog authenticate with their respective integration keys passed as `api_key`.

## Authentication

Webhooks can include an API key for destinations requiring authentication. Prequel signs every payload and includes the signature in the `X-Prequel-Webhook-Signature` header for verification purposes.

## Versioning

At this time, webhook versioning is in flux and is expected to change.

## Payload structure

### Headers

| Header                        | Description                            |
| ----------------------------- | -------------------------------------- |
| `Content-Type`                | Always `application/json`              |
| `X-Prequel-Webhook-Timestamp` | Event send timestamp                   |
| `X-Prequel-Webhook-Signature` | SHA-256 RSA PKCS1 v1.5 signature       |
| `X-Prequel-Webhook-Digest`    | Optional SHA-256 hash for verification |

### Body format

All events follow this structure:

```json title="Webhook payload" icon="brackets-curly" expandable theme={null}
{
  "type": "resource_type.event_type",
  "version": "XXXX-XX-XX",
  "created_at": "...",
  "data": {
    // event-specific content
  }
}
```

## Signature verification

Prequel uses asymmetric cryptography with RSA key pairs. The private key signs payloads; your account's public key verifies authenticity.

### Verification steps

**1. Retrieve Public Key**

Access your webhook public key via the `/public/signatures/webhook-public-key` API endpoint. Fetch this value rather than hardcoding it, since the key may be rotated.

**2. Reconstruct Signing Data**

Extract the timestamp from the `X-Prequel-Webhook-Timestamp` header (RFC 3339 format). Combine timestamp, a period (`.`), and the raw JSON body. Hash this concatenated string using SHA-256.

<Warning>
  Use the raw request body before JSON deserialization, as parsing may introduce subtle changes.
</Warning>

**Validate Body Hash**

The `X-Prequel-Webhook-Digest` header contains the SHA-256 hash of the raw body only. Compare this against your computed hash to verify correct body handling. Do not use this for signature confirmation.

**3. Confirm Signature**

Verify the signing data hash against the signature in `X-Prequel-Webhook-Signature` using your public key with PKCS1 v1.5 scheme. Hex-decode Prequel's signature before comparison.

**4. Check Timestamp**

Implement a time window (e.g., 5 minutes) to reject outdated events and prevent replay attacks.

## Object storage manifest signatures

When data is delivered to an object storage datalake (S3, GCS, ABS, S3-compatible), Prequel writes a signed manifest alongside the data so consumers can verify the manifest came from Prequel. Fetch the verification key with `GET /public/signatures/object-storage-manifest-public-key` and treat it the same way as the webhook public key. Fetch the value dynamically rather than hardcoding it, since the key may rotate.