Outgoing webhook

Outgoing webhooks enable Phare to communicate information to another service using HTTP callbacks. An HTTP POST request with a payload is sent to a designated URL that could be an HTTP endpoint in your own stack or a compatible third party.

​

Configuration

To configure an outgoing webhook, two information are required:

• Callback URL: The URL where the webhook payload will be sent.
• Signing secret: A secret key that will be used to sign the webhook payload, allowing you to verify that the payload was sent by Phare.

Phare generates a safe secret for you, but you can provide your own if needed.

​

Using the integration

Once installed in one of your projects, the outgoing webhook integration can be used when creating new alert rules. A default JSON payload is pre-filled based on the alert event you selected, but you can customize the payload JSON structure to fit your needs.

​

Payload customization

You can use a defined set of variables in the JSON payload to customize the message sent to the webhook, with each alert event having its own set of variables. The structure of the payload is not restricted as long as it is a valid JSON object.

The list of available variables for each alert event is defined as follows:

​

Monitors

​

Incidents

​

Webhook security

Outgoing webhooks sent by Phare are signed with HMAC-SHA256 to ensure that the payload is coming from Phare and has not been tampered with. The signature also includes a timestamp to prevent replay attacks.

Verifying the signature of the webhook payload is done by computing the HMAC-SHA256 of three parts concatenated in a single string with the following format:

{version}.{timestamp}.{payload}

The version is always v0, it is used to ensure backward compatibility in case of future changes to the signature algorithm. The timestamp is sent in the X-Phare-Request-Timestamp header and the signature of the payload is sent in the X-Phare-Request-Signature header.

You can find a few implementation examples below:

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

In case the webhook fails to deliver the payload to the callback URL, Phare will retry sending the payload up to five times with an exponential backoff strategy.

To be considered successful, the webhook must return a status code in the 2xx range within 30 seconds. If the webhook fails to deliver the payload after all retries, the webhook will not be retried again.

The first webhook payload is sent immediately after the event is triggered, in case of failure, the same payload will be resented after 1 minute, then 5 minutes, 10 minutes, and finally 1 hour.

The theoretical maximum time between the first request and the last retry, including the 30-second timeout is 1 hour and 18 minutes.

​

Debugging

To help you troubleshoot issues with your outgoing webhooks, Phare provides a log of all the requests sent to your callback URL including request and response details.