Integrate Outgoing Webhooks with Phare

Want to build your own custom integration or connect Phare to a tool that isn’t officially supported? Outgoing webhooks are your best friend! They send HTTP callbacks with your alert data to any endpoint you specify, perfect for DIY integrations, logging or connecting to specialized systems.

​

Configuration

Setting up an outgoing webhook is straightforward, you just need two pieces of information:

• Callback URL: Where should the data be sent? This could be an endpoint in your own application or a third-party service that accepts webhooks.
• Signing secret: A secret key that proves the data came from Phare and wasn’t tampered with along the way.

A secure signing secret is automatically generated for you, but you’re welcome to use your own if you prefer.

​

Using the integration

Once your webhook is set up, you can connect it to alert rules in your projects. A default JSON payload based on the alert event you’ve chosen will be generated, customize it as needed to fit your specific use case.

​

Payload customization

Make your webhooks work exactly how you want! You can reshape the JSON payload structure any way you like (as long as it’s valid JSON), and use variables to inject dynamic data from the triggering event.

Each alert event type has its own set of available variables. Here’s what you can use:

​

Monitors

​

Incidents

​

Webhook security

Trust but verify! Phare outgoing webhooks come with built-in security through HMAC-SHA256 signatures. This ensures the payloads you receive:

1. Actually came from Phare
2. Haven’t been tampered with in transit
3. Aren’t being replayed from previous requests

To verify a webhook’s authenticity, compute the HMAC-SHA256 of this concatenated string:

{version}.{timestamp}.{payload}

The version is always v0 (this will be bumped if the algorithm ever change). You’ll find the timestamp in the X-Phare-Request-Timestamp header and the signature in the X-Phare-Request-Signature header.

Here are some code examples to help you implement verification:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
    const secret = 'your-signing-secret';
    const version = 'v0';
    const timestamp = req.headers['x-phare-request-timestamp'];
    const signature = req.headers['x-phare-request-signature'];

    const payload = version + ':' + timestamp + ':' + JSON.stringify(req.body);

    const hash = crypto.createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    if (hash === signature) {
        console.log('Signature verified');
    } else {
        console.log('Signature verification failed');
    }
})

​

Retry policy

Network hiccups happen, which is why Phare outgoing webhooks don’t give up easily. If your endpoint doesn’t respond with a 2xx status code within 30 seconds, it will be retried up to five times using an exponential backoff strategy:

1. First attempt: Immediate delivery
2. First retry: After 1 minute
3. Second retry: After 5 minutes
4. Third retry: After 10 minutes
5. Final retry: After 1 hour

This means that from first attempt to last retry, your webhook could arrive anytime within a 1 hour and 18 minute window (including timeouts).

​

Debugging

Webhooks not working as expected? Logs are available with the request and response details making troubleshooting a breeze, you only need to click the row you would like to inspect.