Skip to main content

Configure and use webhooks (Beta)

This topic describes how to configure and use webhooks for event notifications. For more information about the Event Notifications (Beta) feature, see About event notifications (Beta).

Webhooks allow you to receive notifications as HTTP POST requests to an endpoint you control. This enables integration with services like Slack, PagerDuty, custom monitoring systems, and other tools that support webhook integrations. For the JSON envelope and field descriptions, see Webhook payload structure (Beta).

Configure a Slack webhook​

For more information about configuring incoming webhooks with Slack, see the Sending messages using incoming webhooks in the Slack documentation.

To send notifications to a Slack channel using webhooks:

  1. Go to your Slack workspace settings.
  2. Go to Apps > Incoming Webhooks and click Add to Slack.
  3. Select the channel where you want to receive notifications.
  4. Copy the webhook URL.
  5. Create a notification in the Vendor Portal using your Slack webhook URL. See Create an event notification.
  6. Trigger a test event to verify that the webhook is configured properly.

Test webhooks locally​

You can test a webhook locally using a development endpoint that is either publicly accessible, or reachable through a secure tunnel. You can also test webhooks from the Vendor Portal when you create a webhook notification subscription. For more information, see Create an event notification.

When testing webhooks locally, note the following:

  • If you configured a signing secret, the test payload is signed with HMAC-SHA256 using the same X-Replicated-Signature header as real deliveries
  • If you configured custom HTTP headers, they are included in the test request so you can verify your endpoint's authentication logic
  • Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security

To test webhooks against a local development endpoint:

  1. Use a tunnel service like ngrok to expose your local endpoint:

    ngrok http 3000

  2. Enter the ngrok URL as your webhook URL in the notification form:

    https://abc123.ngrok.io/webhook

  3. Click Send test webhook to send a sample payload to your local endpoint through the tunnel.

  4. Check the ngrok dashboard or your application logs to verify the request was received and processed correctly.

Verify webhook signatures​

Event Notifications webhooks include an HMAC-SHA256 signature for verification. This allows you to verify that webhook requests are genuinely from Replicated and have not been tampered with.

When you configure a webhook with a signing secret, Replicated generates an HMAC-SHA256 signature of the webhook payload using your secret. The signature is sent in the X-Replicated-Signature HTTP header. The X-Replicated-Signature header contains the signature in the following format: X-Replicated-Signature: sha256=<hex-encoded-signature>. For example: X-Replicated-Signature: sha256=5d7f8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e.

To verify webhook signatures in your endpoint:

  1. Extract the signature from the X-Replicated-Signature header:

    const signatureHeader = req.headers['x-replicated-signature'];
    const signature = signatureHeader.replace('sha256=', '');

  2. Compute the HMAC-SHA256 signature of the raw request body using your signing secret:

    const crypto = require('crypto');

    const hmac = crypto.createHmac('sha256', signingSecret);
    hmac.update(requestBody); // Use the raw request body string
    const expectedSignature = hmac.digest('hex');

  3. Use a constant-time comparison to prevent timing attacks:

    const crypto = require('crypto');

    function verifySignature(signature, expectedSignature) {
    return crypto.timingSafeEqual(
       Buffer.from(signature, 'hex'),
       Buffer.from(expectedSignature, 'hex')
    );
    }

    if (!verifySignature(signature, expectedSignature)) {
    // Signature verification failed - reject the request
    return res.status(401).send('Invalid signature');
    }

    // Signature verified - process the webhook

About delivery retries and timeouts for webhooks​

The Vendor Portal automatically retries failed webhook deliveries to ensure reliability. When a webhook delivery attempt fails, the Vendor Portal makes up to eight retry attempts. Each delivery attempt times out after five seconds. The retry schedule is approximately 1m, 2m, 4m, 8m, 16m, 32m, 64m, 128m after the first failed attempt.

A webhook delivery is considered failed when:

  • The endpoint responds with a non-2xx status code
  • The request times out (exceeds 5 seconds)
  • A network error occurs (endpoint unreachable, DNS failure, etc.)

After eight retry attempts, the Vendor Portal marks the notification as permanently failed. The Vendor Portal also sends an email to both the subscription creator and team Admins with details about the failure, including the event type, the last error message, and a link to the delivery history in the Vendor Portal.

If a webhook subscription has 10 consecutive permanent failures, the Vendor Portal automatically disables it. To resume deliveries, verify that your endpoint is reachable and then re-enable the subscription from the Notifications page.

About adding custom HTTP headers​

You can add custom HTTP headers to webhook subscriptions to authenticate with your receiving endpoint. This is useful when your endpoint requires an API key, bearer token, or other credentials in the request headers.

Header values are encrypted at rest and masked in the UI after you save the subscription. To update a saved header value, you must re-enter it. Custom headers are included in both real webhook deliveries and test webhook requests.

Custom headers have the following limitations:

  • Maximum of five headers per subscription
  • Header values can be up to 2048 characters
  • Duplicate header names are not allowed
  • Certain reserved headers (such as Content-Type and Host) cannot be overridden
On this page