Generic Webhook Alert Configuration

Configure generic webhooks as an alert destination in Collate.

Generic Webhook Alerts Configuration

The Generic Webhook destination provides maximum flexibility for integrating Collate alerts with virtually any external system. It lets you send alert notifications to custom applications, automation platforms, and internal services that can receive HTTP POST requests.

Use Cases

Generic webhooks are ideal for:

• Custom Applications: Internal tools and applications that need to receive alerts.
• Automation Platforms: Services like Zapier, Make (formerly Integromat), and IFTTT.
• Monitoring Systems: Integration with existing monitoring infrastructure.
• Internal Services: Microservices, APIs, and serverless functions.
• Workflow Automation: Triggering automated workflows and processes.

Preparing Your Webhook Endpoint

Before configuring the webhook in Collate, you need a webhook endpoint URL from your external system. This could be:

• An automation platform like Zapier or Make.
• A custom application or API endpoint.
• An internal service that accepts HTTP POST requests.
• A serverless function (AWS Lambda, Google Cloud Functions, and so on).

Your endpoint must:

• Accept HTTP POST requests.
• Be accessible from your Collate instance.
• Reply with its final response directly. A redirect (3xx) response is treated as a failed delivery, so the configured Endpoint URL should be the exact final URL, not one that redirects elsewhere.

Configuring Generic Webhooks in Collate

Once you have your webhook endpoint URL, follow these steps to configure it in Collate:

Step 1: Access Alert Configuration

1. In Collate, navigate to Alerts & Notifications from the main menu.
2. Select the type of alert you want to configure:
   • Data Observability Alerts (for data quality and pipeline monitoring).
   • System & Governance Notifications (for metadata and governance events).

Step 2: Add Generic Webhook as a Destination

1. Click Add Destination.
2. Select Generic Webhook from the available destination options.
3. Paste your Endpoint URL into the Endpoint URL field (must start with https://).
4. Optional: set an Authentication method so your endpoint can verify requests actually came from Collate. See Authenticating Webhook Requests below.
5. Optional: add custom request headers.

Step 3: Test the Connection

1. Click Test Connection to verify the webhook is working.
2. A test payload will be sent to your endpoint.
3. If successful, you’ll see a confirmation message.
4. Check your external system to verify the test message was received.

Step 4: Save and Enable

1. Click Save to store the configuration.
2. The webhook destination is now ready to receive alerts.

Authenticating Webhook Requests

The Generic Webhook destination supports three ways to authenticate outgoing requests, so your endpoint can confirm they actually came from Collate:

• No authentication: requests carry no credential. Only use this for endpoints on a trusted internal network.
• Bearer token with an HMAC signature: you provide a secret key. Collate never sends this key over the network. Instead, it signs every request with it and sends the signature in the X-OM-Signature header. See Verifying the Signature below.
• OAuth2 client credentials: you provide a token URL, client ID, client secret, and optional scope. Collate exchanges these for an access token using the OAuth2 client-credentials grant, caches the token until it’s close to expiring, and sends it as an Authorization: Bearer <token> header. If your endpoint responds with 401 Unauthorized, Collate fetches a fresh token and retries the request once.

Custom headers are also supported, for example a static API key. Custom headers are stored in plain text and are visible to any user who can view the alert configuration, so don’t put a secret in a custom header. Use the HMAC or OAuth2 option instead.

Verifying the Signature

If you configure the HMAC option, every request includes a header in this form:

X-OM-Signature: sha256=<signature>

<signature> is the HMAC-SHA256 of the exact request body, computed using your secret key and Base64-encoded (not hex-encoded).

To verify a request on your endpoint:

1. Read the raw request body exactly as received, before parsing it as JSON.
2. Compute HMAC-SHA256 of that raw body using your secret key, then Base64-encode the result.
3. Prefix it with sha256= and compare it to the X-OM-Signature header using a constant-time comparison.
4. Reject the request if they don’t match.

The signature doesn’t include a timestamp, so it can’t by itself prevent a captured request from being replayed. Track each event’s id field (see Payload and Event Types below) and ignore any event you’ve already processed to guard against replay.

Request Headers

Every webhook request includes:

• Content-Type: application/json.
• X-OM-Signature: sha256=<signature> (only if you configured the HMAC option).
• Authorization: Bearer <token> (only if you configured OAuth2 client credentials).
• X-Auth-Params-Email: [e-mail], a fixed internal header sent by the publisher on every request. It isn’t related to the authentication options above and isn’t configurable.
• Any custom headers you added.

There’s no header identifying the event type, a delivery ID, or a delivery timestamp. That information is all in the request body, described below.

Payload and Event Types

Each request body is a single ChangeEvent JSON object describing one change in Collate. Its main fields:

Field	Description
id	Unique identifier for this event. Track this to detect and ignore duplicate or replayed deliveries.
eventType	What happened, for example entityCreated, entityUpdated, or entityDeleted.
entityType, entityFullyQualifiedName	What kind of asset changed, and which one.
userName	Who made the change.
timestamp	When the change happened, in Unix epoch milliseconds.
changeDescription	For entityUpdated events, the fields that were added, updated, or deleted.
entity	The full asset, sent as a JSON-encoded string rather than a nested object. Parse it a second time to read it.

The ChangeEvent schema’s own field description for entity says it’s populated only for entityCreated. In practice, Collate populates it for every event type shown above, including entityUpdated and entityDeleted.

For the complete field list and every eventType value, see the ChangeEvent and ChangeEventType schemas.

Delivery Behavior

• Timeouts: by default, Collate allows up to 10 seconds to connect to your endpoint and 12 seconds to receive a response.
• Retries: a failed delivery due to a connection error, a timeout, or a 4xx/5xx response is retried up to 3 times by default. A 3xx (redirect) response is treated as a failed delivery too, but isn’t retried.
• Ordering: events aren’t guaranteed to arrive in order, so sort by each event’s timestamp rather than assuming delivery order.

Network Considerations

Collate doesn’t publish a fixed outbound IP address for webhook delivery. If your endpoint’s firewall needs a specific source IP allowlisted, contact your Collate representative.

Collate’s PrivateLink support secures traffic going into Collate (users, applications, and ingestion services reaching Collate). It doesn’t cover this direction: Collate delivering a webhook out to your endpoint. Your endpoint still needs to be reachable over the public internet, or over a network Collate already has a route to.

Best Practices

• Use HTTPS: Always use HTTPS endpoints for security.
• Authenticate Requests: Configure HMAC or OAuth2 authentication so your endpoint can reject unsigned or forged requests.
• Error Handling: Ensure your endpoint handles errors gracefully and logs failures.
• Response Time: Keep endpoint response times under the read timeout (12 seconds by default, see Delivery Behavior above).
• Multiple Webhooks: Configure multiple webhook endpoints for different alert types.
• Testing: Always test your webhook connection before enabling in production.
• Validation: Validate incoming data in your endpoint before processing.