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

Monitor Created

Variable	Value
$PROJECT_ID	Id of the project this monitor belongs to
$PROJECT_NAME	Name of the project this monitor belongs to
$PROJECT_SLUG	Slug of the project this monitor belongs to
$MONITOR_ID	Id of the monitor
$MONITOR_NAME	Name of the monitor
$MONITOR_STATUS	Status of the monitor
$MONITOR_PROTOCOL	Protocol used by the monitor
$MONITOR_REQUEST	Object containing request information for the monitor
$MONITOR_REGIONS	Array of regions where the monitor is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor

Monitor Deleted

Variable	Value
$PROJECT_ID	Id of the project this monitor belongs to
$PROJECT_NAME	Name of the project this monitor belongs to
$PROJECT_SLUG	Slug of the project this monitor belongs to
$MONITOR_ID	Id of the monitor
$MONITOR_NAME	Name of the monitor
$MONITOR_STATUS	Status of the monitor
$MONITOR_PROTOCOL	Protocol used by the monitor
$MONITOR_REQUEST	Object containing request information for the monitor
$MONITOR_REGIONS	Array of regions where the monitor is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor

Monitor Certificate Discovered

Variable	Value
$PROJECT_ID	Id of the project this monitor belongs to
$PROJECT_NAME	Name of the project this monitor belongs to
$PROJECT_SLUG	Slug of the project this monitor belongs to
$MONITOR_ID	Id of the monitor
$MONITOR_NAME	Name of the monitor
$MONITOR_STATUS	Status of the monitor
$MONITOR_PROTOCOL	Protocol used by the monitor
$MONITOR_REQUEST	Object containing request information for the monitor
$MONITOR_REGIONS	Array of regions where the monitor is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor
$CERTIFICATE_SERIAL_NUMBER	Serial number of the certificate
$CERTIFICATE_SUBJECT_COMMON_NAME	Common name of the certificate
$CERTIFICATE_SUBJECT_ALTERNATIVE_NAMES	Subject alternative names of the certificate
$CERTIFICATE_ISSUER_COMMON_NAME	Issuer common name of the certificate
$CERTIFICATE_ISSUER_ORGANIZATION	Issuer organization of the certificate
$CERTIFICATE_NOT_BEFORE	Not before date of the certificate
$CERTIFICATE_NOT_AFTER	Not after date of the certificate

Monitor Certificate Expiring

Variable	Value
$PROJECT_ID	Id of the project this monitor belongs to
$PROJECT_NAME	Name of the project this monitor belongs to
$PROJECT_SLUG	Slug of the project this monitor belongs to
$MONITOR_ID	Id of the monitor
$MONITOR_NAME	Name of the monitor
$MONITOR_STATUS	Status of the monitor
$MONITOR_PROTOCOL	Protocol used by the monitor
$MONITOR_REQUEST	Object containing request information for the monitor
$MONITOR_REGIONS	Array of regions where the monitor is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor
$CERTIFICATE_SERIAL_NUMBER	Serial number of the certificate
$CERTIFICATE_SUBJECT_COMMON_NAME	Common name of the certificate
$CERTIFICATE_SUBJECT_ALTERNATIVE_NAMES	Subject alternative names of the certificate
$CERTIFICATE_ISSUER_COMMON_NAME	Issuer common name of the certificate
$CERTIFICATE_ISSUER_ORGANIZATION	Issuer organization of the certificate
$CERTIFICATE_NOT_BEFORE	Not before date of the certificate
$CERTIFICATE_NOT_AFTER	Not after date of the certificate

Incidents

Incident Created

Variable	Value
$PROJECT_ID	Id of the project this incident belongs to
$PROJECT_NAME	Name of the project this incident belongs to
$PROJECT_SLUG	Slug of the project this incident belongs to
$MONITOR_ID	Id of the monitor that triggered the incident
$MONITOR_NAME	Name of the monitor that triggered the incident
$MONITOR_STATUS	Status of the monitor that triggered the incident
$MONITOR_PROTOCOL	Protocol used by the monitor that triggered the incident
$MONITOR_REQUEST	Object containing request information for the monitor that triggered the incident
$MONITOR_REGIONS	Array of regions where the monitor that triggered the incident is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor that triggered the incident
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor that triggered the incident
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor that triggered the incident
$INCIDENT_ID	Id of the incident
$INCIDENT_SLUG	Slug of the incident
$INCIDENT_TITLE	Title of the incident
$INCIDENT_ERROR	Error message of the incident
$INCIDENT_STATE	State of the incident
$INCIDENT_STATUS	Status of the incident
$INCIDENT_IMPACT	Impact of the incident

Incident Recovered

Variable	Value
$PROJECT_ID	Id of the project this incident belongs to
$PROJECT_NAME	Name of the project this incident belongs to
$PROJECT_SLUG	Slug of the project this incident belongs to
$MONITOR_ID	Id of the monitor that triggered the incident
$MONITOR_NAME	Name of the monitor that triggered the incident
$MONITOR_STATUS	Status of the monitor that triggered the incident
$MONITOR_PROTOCOL	Protocol used by the monitor that triggered the incident
$MONITOR_REQUEST	Object containing request information for the monitor that triggered the incident
$MONITOR_REGIONS	Array of regions where the monitor that triggered the incident is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor that triggered the incident
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor that triggered the incident
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor that triggered the incident
$INCIDENT_ID	Id of the incident
$INCIDENT_SLUG	Slug of the incident
$INCIDENT_TITLE	Title of the incident
$INCIDENT_ERROR	Error message of the incident
$INCIDENT_STATE	State of the incident
$INCIDENT_STATUS	Status of the incident
$INCIDENT_IMPACT	Impact of the incident

Incident Comment Created

Variable	Value
$PROJECT_ID	Id of the project this incident belongs to
$PROJECT_NAME	Name of the project this incident belongs to
$PROJECT_SLUG	Slug of the project this incident belongs to
$MONITOR_ID	Id of the monitor that triggered the incident
$MONITOR_NAME	Name of the monitor that triggered the incident
$MONITOR_STATUS	Status of the monitor that triggered the incident
$MONITOR_PROTOCOL	Protocol used by the monitor that triggered the incident
$MONITOR_REQUEST	Object containing request information for the monitor that triggered the incident
$MONITOR_REGIONS	Array of regions where the monitor that triggered the incident is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor that triggered the incident
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor that triggered the incident
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor that triggered the incident
$INCIDENT_ID	Id of the incident
$INCIDENT_SLUG	Slug of the incident
$INCIDENT_TITLE	Title of the incident
$INCIDENT_ERROR	Error message of the incident
$INCIDENT_STATE	State of the incident
$INCIDENT_STATUS	Status of the incident
$INCIDENT_IMPACT	Impact of the incident
$USER_ID	Id of the user who created the comment
$USER_EMAIL	Email of the user who created the comment
$INCIDENT_COMMENT_ID	Id of the comment
$INCIDENT_COMMENT_CONTENT	Content of the comment

Incident Update Publish

Variable	Value
$PROJECT_ID	Id of the project this incident belongs to
$PROJECT_NAME	Name of the project this incident belongs to
$PROJECT_SLUG	Slug of the project this incident belongs to
$MONITOR_ID	Id of the monitor that triggered the incident
$MONITOR_NAME	Name of the monitor that triggered the incident
$MONITOR_STATUS	Status of the monitor that triggered the incident
$MONITOR_PROTOCOL	Protocol used by the monitor that triggered the incident
$MONITOR_REQUEST	Object containing request information for the monitor that triggered the incident
$MONITOR_REGIONS	Array of regions where the monitor that triggered the incident is running
$MONITOR_INTERVAL	Interval in seconds between each check for the monitor that triggered the incident
$MONITOR_INCIDENT_CONFIRMATIONS	Number of confirmations required to trigger an incident for the monitor that triggered the incident
$MONITOR_RECOVERY_CONFIRMATIONS	Number of confirmations required to recover from an incident for the monitor that triggered the incident
$INCIDENT_ID	Id of the incident
$INCIDENT_SLUG	Slug of the incident
$INCIDENT_TITLE	Title of the incident
$INCIDENT_ERROR	Error message of the incident
$INCIDENT_STATE	State of the incident
$INCIDENT_STATUS	Status of the incident
$INCIDENT_IMPACT	Impact of the incident
$USER_ID	Id of the user who published the update
$USER_EMAIL	Email of the user who published the update
$INCIDENT_UPDATE_ID	Id of the update
$INCIDENT_UPDATE_STATE	State of the update
$INCIDENT_UPDATE_CONTENT	Content of the update

Webhook security

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

Actually came from Phare
Haven’t been tampered with in transit
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');
    }
})

Pro security tip: Always check that the timestamp isn’t too old, it is recommended to reject a webhook older than 5 minutes to prevent replay attacks.

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:

First attempt: Immediate delivery
First retry: After 1 minute
Second retry: After 5 minutes
Third retry: After 10 minutes
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.

Get Started

Uptime

Integrations

Integrate Outgoing Webhooks with Phare

Configuration

Using the integration

Payload customization

Monitors

Incidents

Webhook security

Retry policy

Debugging

Get Started

Uptime

Integrations

​Configuration

​Using the integration

​Payload customization

​Monitors

​Incidents

​Webhook security

​Retry policy

​Debugging

Configuration

Using the integration

Payload customization

Monitors

Incidents

Webhook security

Retry policy

Debugging