Skip to main content
You may wish to create endpoints to receive asynchronous events from your Prequel integration, such as transfer failures. Webhook endpoints created using the POST /webhooks endpoint can subscribe to any of Prequel’s Event Types and configure delivery via HTTPS, Slack, or Pagerduty. Choose a delivery method to get started:

Slack webhooks

Deliver events into a Slack channel for the team to triage.

Datadog webhooks

Forward events into Datadog as monitor-ready events.

Generic HTTP webhooks

Send HTTPS POST or GET callbacks to your own receiver.
For receiving sensitive trace alerts during transfers, see Sensitive Trace Webhooks.

​
Delivery methods

​
HTTP POST and GET

Prequel supports HTTPS callbacks to your custom webhook receiver. Creating a webhook endpoint as the generic_post type will cause payloads to be sent as a JSON payload. The generic_get type will deliver payloads as URL parameters. The payloads are defined in Event Types.

​
PagerDuty, Slack & Datadog

You may want to have events sent to specific vendors for special handling of webhook requests. Currently, PagerDuty, Slack and Datadog are supported, with specific payload shapes according to the vendor specifications. For detailed instructions on integrating Prequel webhooks with Slack or Datadog please visit the following pages:

​
Authentication

You can provide an API key for the webhook to use if the destination requires one. Additionally, Prequel signs every payload and passes the signature through the X-Prequel-Webhook-Signature header. See Verifying Webhooks for more information on handling the signature.

​
Versioning

Prequel uses a top-level api_version field. A version is represented by the date it was released. Currently, all webhooks use the version 2023-10-15.

​
Contents & structure

All event types follow this structure:

​
Headers

HeaderDescription
Content-TypeAlways application/json
X-Prequel-Webhook-TimestampTimestamp generated when the event is sent.
X-Prequel-Webhook-SignatureSignature generated by Prequel using SHA-256 and RSA PKCS1 v1.5 signature scheme. See Verifying Webhooks.
X-Prequel-Webhook-DigestOptional utility for signature verification. See Verifying Webhooks.

​
Body

Body structure
{
  "type": "resource.event",
  "api_version": "XXXX-XX-XX",
  "created_at": ..., // timestamp generated when the event is created
  "data": {
    // event specific
  }
}

​
Event types

When creating a webhook, you must specify which events it should listen to. Webhooks created before October 31 2023 will continue to receive only transfer errors. Webhooks are available for the following event types:
  • transfer.success
  • transfer.error
  • transfer.cancelled
  • export_source.created
  • export_source.updated
  • export_source.deleted
  • export_destination.created
  • export_destination.updated
  • export_destination.deleted
  • recipient.created
  • recipient.updated
  • recipient.deleted
  • export_magic_link.created
  • export_magic_link.deleted
Each event type’s payload is shown below. Select a tab to see the example for a given event.

​
Transfer events

This event has type transfer.success. It is sent whenever Prequel identifies a successful transfer.
transfer.success payload
{
  "type":"transfer.success",
  "api_version": "2023-10-15",
  "created_at": "2023-10-15T19:19:08+00:00",
  "data":{
    "destination_id":"00000000-0000-0000-0000-000000000000",
    "destination_name":"Foo Bar",
    "id_in_provider_system":"acme",
    "in_app_url":"https://app.prequel.co/destinations/00000000-0000-0000-0000-000000000000",
    "is_full_refresh":true,
    "models":["users"],
    "rows_transferred":1000,
    "transfer_id":"00000000-0000-0000-0000-000000000000",
    "transfer_log":"users - succeeded",
    "transfer_log_pretty":"users - succeeded",
    "transfer_started_at": "2023-10-15T16:19:08+00:00",
    "transfer_ended_at": "2023-10-15T18:19:08+00:00",
    "transfer_status":"SUCCESS"
  },
}

​
Source events

This event has type export_source.created. It is sent whenever Prequel identifies that a new source has been created. This example shows a new Snowflake source.
export_source.created payload
{
  "type": "export_source.created",
  "api_version": "2023-10-15",
  "created_at": "2025-02-20T17:54:18.453379Z",
  "data": {
    "current_resource": {
      "id": "00000000-0000-0000-0000-000000000000",
      "host": "snowflake-webhook.region.cloud.snowflakecomputing.com",
      "name": "Acme Inc",
      "port": 443,
      "vendor": "snowflake",
      "database": "source_database",
      "username": "snowflake_user",
      "created_at": "2025-02-20T12:54:18.445223-05:00",
      "updated_at": "2025-02-20T12:54:18.445223-05:00",
      "disable_ssl": false,
      "use_ssh_tunnel": false,
      "ssh_tunnel_host": "",
      "ssh_tunnel_port": 22,
      "ssh_tunnel_username": "",
      "gcp_iam_role_metadata": {
        "type": "",
        "audience": "",
        "token_url": "",
        "credential_source": {
          "url": "",
          "region_url": "",
          "environment_id": "",
          "regional_cred_verification_url": ""
        },
        "subject_token_type": "",
        "service_account_impersonation_url": ""
      },
      "max_concurrent_transfers": 1,
      "is_bucket_credentials_implicit": false,
      "max_concurrent_queries_per_transfer": 1
    },
    "previous_resource": null
  }
}

​
Destination events

This event has type export_destination.created. It is sent whenever Prequel identifies that a new destination has been created.
export_destination.created payload
{
  "type": "export_destination.created",
  "api_version": "2023-10-15",
  "created_at": "2025-02-20T18:12:45.409267Z",
  "data": {
    "current_resource": {
      "id": "00000000-0000-0000-0000-000000000000",
      "host": "snowflake-webhook.region.cloud.snowflakecomputing.com",
      "name": "Acme Inc",
      "port": 443,
      "schema": "webhook_schema",
      "vendor": "snowflake",
      "database": "destination_db",
      "products": ["billing", "invoices"],
      "username": "snowflake_user",
      "created_at": "2025-02-20T13:12:45.360283-05:00",
      "is_enabled": true,
      "updated_at": "2025-02-20T13:12:45.360283-05:00",
      "disable_ssl": false,
      "recipient_id": "00000000-0000-0000-0000-000000000000",
      "enabled_models": ["*"],
      "use_ssh_tunnel": false,
      "ssh_tunnel_host": "",
      "ssh_tunnel_port": 0,
      "frequency_minutes": 0,
      "ssh_tunnel_username": "",
      "gcp_iam_role_metadata": {
        "type": "",
        "audience": "",
        "token_url": "",
        "credential_source": {
          "url": "",
          "region_url": "",
          "environment_id": "",
          "regional_cred_verification_url": ""
        },
        "subject_token_type": "",
        "service_account_impersonation_url": ""
      },
      "id_in_provider_system": "tenant_id",
      "max_concurrent_transfers": 1,
      "is_bucket_credentials_implicit": false,
      "last_successful_transfer_ended_at": null,
      "max_concurrent_queries_per_transfer": 1
    },
    "previous_resource": null
  }
}

​
Recipient events

This event has type recipient.created. It is sent whenever Prequel identifies that a new recipient has been created.
recipient.created payload
{
  "type": "recipient.created",
  "api_version": "2023-10-15",
  "created_at": "2025-02-20T17:44:10.769913Z",
  "data": {
    "current_resource": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Acme Inc",
      "id_in_provider_system": "acme_inc",
      "products": ["billing", "invoices"],
      "created_at": "2025-02-20T12:44:10.763224-05:00",
      "updated_at": "2025-02-20T12:44:10.763224-05:00",
    },
    "previous_resource": null
  }
}

​
Verifying webhooks

Prequel provides a unique signature in the HTTP header of each webhook request. You can use this signature and your account’s webhook public key to verify that the data you receive is from Prequel.

​
Webhook signatures

Prequel’s approach to webhook signatures is based on asymmetric cryptography. Prequel generates an RSA private and public key pair for your account’s webhook integration. After generating a webhook, Prequel digitally signs the payload with the private key. On receiving the webhook, you can use the public key to verify the authenticity and freshness of this signature. See Verify the signature.

​
Relevant headers

HeaderDescription
X-Prequel-Webhook-TimestampTimestamp the webhook was sent, in RFC 3339 format.
X-Prequel-Webhook-SignatureHex-encoded signature generated by Prequel using the signing data.
(Maybe) X-Prequel-Webhook-DigestHex-encoded SHA-256 hash of the payload only, provided by Prequel for debugging purposes.

​
Verify the signature

The general steps to verify a signature are outlined below.

​
1. Retrieve your current webhook key

You can retrieve your current webhook key by hitting the following API endpoint /public/signatures/webhook-public-key.

​
2. Reconstruct the signing data

Extract the timestamp provided in the X-Prequel-Webhook-Timestamp header. The date is in RFC 3339 format and looks something like: X-Prequel-Webhook-Timestamp: 2023-10-15T14:30:00Z The signing data is in the format timestamp.body, constructed by concatenating
  • The timestamp
  • The character .
  • The request body, i.e. the raw JSON payload
Finally, hash the full signing data using SHA-256.
Prequel uses the raw body of the request to generate a signature. You should hash the raw body string (or bytes) before deserializing the JSON payload. Frameworks that parse the response body may introduce subtle changes, such as removing characters or changing key-sort order.
Validate the response hash
Prequel hashes the raw body only and provides the result in the X-Prequel-Webhook-Digest header. You can use this to validate that you are handling the response body correctly by hex-decoding the value and comparing it to your SHA-256 hash of the raw body. You should not use this to confirm the signature.

​
3. Confirm the signature

Once you’ve reconstructed and hashed the signing data, you can sign the data with your public key and compare the output to the signature in the X-Prequel-Webhook-Signature header. Make sure to decode Prequel’s signature from hex before comparing. Prequel uses the PKCS1 v1.5 signature scheme.

​
4. Verify timing

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. The provided timestamp is verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. However, even if the attacker cannot alter the data, they may produce side-effects from processing the same event multiple times. We recommend defining a time window (such as 5 minutes) and rejecting events that are too old.