Integrate Outgoing Webhooks with Phare
Receive alerts by webhooks on third-party tools or build your own integration.
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
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
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
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
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
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
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
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
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:
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:
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.