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

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

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

Incidents

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

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

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

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

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:

You should also ensure that the timestamp is not too old to prevent replay attacks. A good practice is to check that the timestamp is not older than 5 minutes.

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.

Get Started

Uptime

Integrations

Outgoing webhook

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