Record API

A webhook_record destination delivers one HTTP request per record. For the API call to register a destination with Prequel, including a complete example, see Create Destination. For higher-volume workloads, consider the Batch API, which delivers multiple records per request.

Register

Declare your schema and request template within Prequel.

Receive

Receive and process the record in the request body.

Respond

Return a status code Prequel acts on.

Acknowledge

Optionally, report the outcome of each record.

Authentication

Prequel signs every delivery request with the X-Prequel-Webhook-Signature header so your endpoint can validate the request originated from Prequel. Fetch the public key for verification from GET /public/signatures/webhook-public-key. See Webhook headers for the full header list and verification steps.

Creating your destination spec

The destination object allows you to customize the contract between data shared by your customers and the shape Prequel provides to your receiving endpoint. Example: Suppose you are importing a users table with string fields id, email, and subscription. Below are four possible shapes for a webhook_record destination. These are not exhaustive and features can be combined to conform to your endpoint’s requirements:

Schema as body: Each request body is the record in the shape declared by record_schema, with no additional shaping.
Custom body: Use a body template to customize each record.
Routed by provider: uri and/or headers vary at delivery time using the ProviderID delivery-level identifier.
Destination per provider: A separate destination is registered for each provider, with a record_schema that includes provider-specific custom fields.

Schema as body
Custom body
Routed by provider
Destination per provider

Destination spec you register

POST /import/destinations

{
  "name": "users-record-destination",
  "type": "webhook_record",
  "record_schema": {
    "type": "object",
    "properties": {
      "id":    { "type": "string" },
      "email": { "type": "string" },
      "subscription": { "type": "string" }
    },
    "required": ["id", "email"]
  },
  "webhook_record": {
    "request_template": {
      "method": "POST",
      "uri": "https://example.com/prequel/records",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

What Prequel sends to your endpoint

Webhook request

POST https://example.com/prequel/records
Content-Type: application/json
X-Prequel-Webhook-Timestamp: 2026-01-01T00:00:00Z
X-Prequel-Webhook-Signature: 4f81c9a2...
X-Prequel-Webhook-Digest: sha256=9c1e5b8d...

{
  "id": "usr_001",
  "email": "jane@acme.com",
  "subscription": "pro"
}

Name your destination

Set name (string, required) to a unique identifier for this destination within your account.

Set the destination type

Set type (string, required) to webhook_record for record deliveries.

Declare your record schema

Set record_schema (object, required) to a JSON Schema (draft-07) document that declares the fields each record contains. Prequel validates records against this schema before delivery.

Configure the request template

Set webhook_record.request_template (object, required) with the HTTP method (string, defaults to POST), uri (string, required), and optional headers (object). The uri and headers templates support the .Prequel.* namespace, .Record.* fields, and .IsDeleted. With no body template, Prequel sends each record as a JSON object.

Tune optional throughput limits

Optionally set webhook_record.max_records_per_minute (integer, default 3000) and webhook_record.max_concurrency (integer, default 1) to control delivery throughput.

Destination spec you register

POST /import/destinations

{
  "name": "users-record-destination",
  "type": "webhook_record",
  "record_schema": {
    "type": "object",
    "properties": {
      "id":    { "type": "string" },
      "email": { "type": "string" },
      "subscription": { "type": "string" }
    },
    "required": ["id", "email"]
  },
  "webhook_record": {
    "request_template": {
      "method": "POST",
      "uri": "https://example.com/prequel/records",
      "headers": { "Content-Type": "application/json" },
      "body": "{\"email\": \"{{.Record.email}}\", \"user\": {{.Record.AsJson}}, \"is_deleted\": {{.IsDeleted}}, \"provider_id\": \"{{.Prequel.ProviderID}}\", \"load_id\": \"{{.Prequel.LoadID}}\"}"
    }
  }
}

What Prequel sends to your endpoint

Webhook request

POST https://example.com/prequel/records
Content-Type: application/json
X-Prequel-Webhook-Timestamp: 2026-01-01T00:00:00Z
X-Prequel-Webhook-Signature: 4f81c9a2...
X-Prequel-Webhook-Digest: sha256=9c1e5b8d...

{
  "email": "jane@acme.com",
  "user": {
    "id": "usr_001",
    "email": "jane@acme.com",
    "subscription": "pro"
  },
  "is_deleted": false,
  "provider_id": "b6f2d1a4-3c58-4d0a-9e7b-2f1c8a9d4e63",
  "load_id": "7e0c2b9a-5d14-4f6e-8a3b-9c47d0e15f28"
}

Name your destination

Set name (string, required) to a unique identifier for this destination within your account.

Set the destination type

Set type (string, required) to webhook_record for record deliveries.

Declare your record schema

Set record_schema (object, required) to a JSON Schema (draft-07) document that declares the fields each record contains. Prequel validates records against this schema before delivery.

Configure the request template with a body template

Set webhook_record.request_template (object, required) with method, uri, headers, and body. The body template renders once per request and becomes the HTTP body, with access to record fields, the deletion flag, and delivery-level identifiers. The uri and headers templates have access to the same variables, scoped to .Prequel.*, .Record.*, and .IsDeleted. See Template variables for the full list of available variables. To validate delivery context, render values like {{.Prequel.ProviderID}} and {{.Prequel.LoadID}} into the body and check them on receipt.

Tune optional throughput limits

Optionally set webhook_record.max_records_per_minute (integer, default 3000) and webhook_record.max_concurrency (integer, default 1) to control delivery throughput.

Destination spec you register

POST /import/destinations

{
  "name": "users-record-destination",
  "type": "webhook_record",
  "record_schema": {
    "type": "object",
    "properties": {
      "id":    { "type": "string" },
      "email": { "type": "string" },
      "subscription": { "type": "string" }
    },
    "required": ["id", "email"]
  },
  "webhook_record": {
    "request_template": {
      "method": "POST",
      "uri": "https://example.com/prequel/records?provider={{.Prequel.ProviderID}}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

What Prequel sends to your endpoint

Webhook request

POST https://example.com/prequel/records?provider=b6f2d1a4-3c58-4d0a-9e7b-2f1c8a9d4e63
Content-Type: application/json
X-Prequel-Webhook-Timestamp: 2026-01-01T00:00:00Z
X-Prequel-Webhook-Signature: 4f81c9a2...
X-Prequel-Webhook-Digest: sha256=9c1e5b8d...

{
  "id": "usr_001",
  "email": "jane@acme.com",
  "subscription": "pro"
}

Name your destination

Set name (string, required) to a unique identifier for this destination within your account.

Set the destination type

Set type (string, required) to webhook_record for record deliveries.

Declare your record schema

Set record_schema (object, required) to a JSON Schema (draft-07) document that declares the fields each record contains. Prequel validates records against this schema before delivery.

Route by provider in the request template

Set webhook_record.request_template (object, required) with method, uri, and optional headers. Use {{.Prequel.ProviderID}} in uri and headers to route by the provider whose data is being delivered. .Record.* fields and .IsDeleted are also available if you need to route by record content. See Template variables for the full list of available variables.

Tune optional throughput limits

Optionally set webhook_record.max_records_per_minute (integer, default 3000) and webhook_record.max_concurrency (integer, default 1) to control delivery throughput.

Destination spec you register

POST /import/destinations

{
  "name": "acme-corp-record-destination",
  "type": "webhook_record",
  "record_schema": {
    "type": "object",
    "properties": {
      "id":      { "type": "string" },
      "email":   { "type": "string" },
      "subscription": { "type": "string" },
      "tax_id":  { "type": "string" }
    },
    "required": ["id", "email", "tax_id"]
  },
  "webhook_record": {
    "request_template": {
      "method": "POST",
      "uri": "https://example.com/prequel/records/acme-corp",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

What Prequel sends to your endpoint

Webhook request

POST https://example.com/prequel/records/acme-corp
Content-Type: application/json
X-Prequel-Webhook-Timestamp: 2026-01-01T00:00:00Z
X-Prequel-Webhook-Signature: 4f81c9a2...
X-Prequel-Webhook-Digest: sha256=9c1e5b8d...

{
  "id": "usr_001",
  "email": "jane@acme.com",
  "subscription": "pro",
  "tax_id": "US-77-1234567"
}

Create a separate destination for each provider whose requirements differ. Give each one a name (string, required) that identifies the provider it serves.

Set the destination type

Set type (string, required) to webhook_record for record deliveries.

Declare a provider-specific record schema

Set record_schema (object, required) to a JSON Schema (draft-07) document that declares the fields this provider sends, including any custom fields unique to them. Prequel validates records against this schema before delivery.

Configure the request template

Set webhook_record.request_template (object, required) with method, uri, and optional headers. Because the destination is scoped to a single provider, you can hard-code provider-specific routing into uri and headers without needing template variables.

Tune optional throughput limits

Optionally set webhook_record.max_records_per_minute (integer, default 3000) and webhook_record.max_concurrency (integer, default 1) to control delivery throughput.

Template variables

The body, uri, and headers templates all have access to every variable below.

Variable	Type	Description
`{{.Record.<field>}}`	`any`	Value of a specific field from the record (e.g. `{{.Record.email}}`). The field must be declared in `record_schema`.
`{{.Record.AsJson}}`	`object`	The full record serialized as a JSON object.
`{{.IsDeleted}}`	`boolean`	`true` when Prequel is delivering a record deletion, `false` otherwise.
`{{.Prequel.ProviderID}}`	`string`	Identifier for the provider whose data is being delivered.
`{{.Prequel.LoadID}}`	`string`	Identifier for the active load job.
`{{.Prequel.DestinationID}}`	`string`	Identifier for the destination receiving this delivery.
`{{.Prequel.StreamID}}`	`string`	Identifier for the stream this delivery came from.
`{{.Prequel.RecordAcknowledgementURL}}`	`string`	URL to `PUT` this record’s acknowledgement to. See Acknowledgements.
`{{.Prequel.TenantID}}`	`string`	Identifier for the tenant the stream belongs to.
`{{.Prequel.IsTest}}`	`boolean`	`true` when the delivery comes from a test load.

Webhook headers

Prequel includes the following headers on every delivery request.

Header	Description
`X-Prequel-Webhook-Signature`	SHA-256 RSA PKCS1 v1.5 signature of the payload. To verify, fetch the public key from `GET /public/signatures/webhook-public-key` and check the hex-decoded signature against the SHA-256 of `<X-Prequel-Webhook-Timestamp>.<raw body>` using PKCS1 v1.5.
`X-Prequel-Webhook-Timestamp`	RFC 3339 timestamp of when the request was sent. Reject stale timestamps to prevent replay attacks.
`X-Prequel-Webhook-Digest`	SHA-256 hash of the raw request body.
`Content-Type`	For batch deliveries, defaults to `application/json` unless overridden by the `headers` template. Record deliveries send only the headers the `headers` template specifies.
`X-Prequel-Is-Test`	Sent with value `true` only on deliveries from a test load. Acknowledgements uploaded for test deliveries are not ingested.
`X-Prequel-Idempotency-Key`	Unique idempotency key across retry attempts of the same batch or record within a load job.
`Content-Type`	Defaults to `application/json` unless overridden by the `headers` template.

Response codes

Your endpoint should return the following response codes.

Code	When to return it	What Prequel does
`2xx`	You accepted the record.	Records the delivery as successful.
`429`, `503`, `504` with a `Retry-After` header	You are rate limited or temporarily unavailable and want the delivery attempted again.	Waits the interval the header specifies, capped at 30 seconds, then retries, for a maximum of three attempts per delivery.
`400`, `412`, `413`, `422`	The payload itself is the problem. Return `422` for schema or data validation failures, `413` when it exceeds your size limit, and `400` when the request is malformed.	Records the delivery as rejected by your endpoint. Does not retry.
Any other status	Your system could not accept the delivery.	Records the delivery as failed at the destination. This includes `500` and `502`, and a `429`, `503`, or `504` whose `Retry-After` header is absent or unparseable. Does not retry.

For more detail on this retry behavior see:

Delivery failure handling

Retry rules, redelivery across loads, and the circuit breakers that stop a failing stream.

Error codes

Prequel records the error code below against the record, so return the status that best describes the failure. Use 422 for schema and data validation problems.

Status	Error code	Title
`400`	`PRQL-JPDQ`	Import Destination Bad Request
`403`	`PRQL-CNJK`	Import Destination Forbidden
`404`	`PRQL-VFTB`	Import Destination Not Found
`412`	`PRQL-BVFF`	Import Destination Precondition Failed
`413`	`PRQL-QAHC`	Import Destination Payload Too Large
`422`	`PRQL-NROT`	Import Destination Unprocessable Entity
`429`	`PRQL-WQKF`	Import Destination Rate Limited
`431`	`PRQL-QFJW`	Import Destination Headers Too Large
`500`	`PRQL-PHOK`	Import Destination Internal Server Error
`502`	`PRQL-QPMF`	Import Destination Bad Gateway
`503`	`PRQL-HNNX`	Import Destination Service Unavailable
`504`	`PRQL-PRHQ`	Import Destination Gateway Timeout
Other `4xx`	`PRQL-IMEK`	Import Destination Client Error
Other `5xx`	`PRQL-TNXG`	Import Destination Server Error

Acknowledgements

Without an acknowledgement, a record your pipeline rejects an hour later still counts as delivered. Acknowledging makes that failure visible to you and to the Provider who can fix it.

Acknowledgements

Report each record’s downstream outcome back to Prequel once your system has processed it.

Getting started

Core concepts

Features

Logging, Monitoring, and Observability

Sources

Security & compliance

Developer SDKs

Register

Receive

Respond

Acknowledge

Authentication

Creating your destination spec

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Template variables

Webhook headers

Response codes

Delivery failure handling

Error codes

Acknowledgements

Acknowledgements

Register

Receive

Respond

Acknowledge

​Authentication

​Creating your destination spec

​Destination spec you register

​What Prequel sends to your endpoint

​Destination spec you register

​What Prequel sends to your endpoint

​Destination spec you register

​What Prequel sends to your endpoint

​Destination spec you register

​What Prequel sends to your endpoint

​Template variables

​Webhook headers

​Response codes

Delivery failure handling

​Error codes

​Acknowledgements

Acknowledgements

Authentication

Creating your destination spec

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Destination spec you register

What Prequel sends to your endpoint

Template variables

Webhook headers

Response codes

Error codes

Acknowledgements