Skip to main content

​
Generic Webhook Alerts Configuration

The Generic Webhook destination provides maximum flexibility for integrating OpenMetadata alerts with virtually any external system. It allows you to 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 OpenMetadata, 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 (for example, AWS Lambda or Google Cloud Functions)
Your endpoint must:
  • Accept HTTP POST requests
  • Be accessible from your OpenMetadata 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 OpenMetadata

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

​
Step 1: Access Alert Configuration

  1. In OpenMetadata, navigate to Alerts & Notifications from the main menu
  2. Select the type of alert you want to configure:

​
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 OpenMetadata. 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 OpenMetadata:
  • 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. OpenMetadata 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. OpenMetadata 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, OpenMetadata 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:
<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)
  • 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 OpenMetadata. Its main fields: For the complete field list and every eventType value, see the ChangeEvent and ChangeEventType schemas.

​
Delivery Behavior

  • Timeouts: by default, OpenMetadata allows up to 10 seconds to connect to your endpoint and 12 seconds to receive a response.
  • Retries: a failed delivery (a connection error, a timeout, or a 4xx/5xx response) is retried up to 3 times by default. A 3xx response is treated as an immediate failure and 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

OpenMetadata doesn’t provide a fixed, published outbound IP address for webhook delivery. Requests originate from wherever your OpenMetadata server is deployed, so the source IP depends on your own infrastructure (for example, a cloud NAT gateway). If your endpoint’s firewall needs a specific source IP allowlisted, check with whoever manages your OpenMetadata deployment’s network egress. OpenMetadata doesn’t offer a VPN or PrivateLink-style connection for webhook delivery. Your endpoint needs to be reachable over the public internet, or over a network your OpenMetadata server 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 well under the 12-second default read timeout
  • Multiple Webhooks: You can 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