Introduction
Webhooks notify your software when events happen within your Foxglove organization.
When you create a webhook, notifications about events are delivered to your webhook endpoint as HTTPS POST requests with a JSON body.
Go to the Webhooks settings page to view a recent history of successful and failed deliveries.
Concepts
Endpoints
Webhooks deliver POST requests to an HTTPS endpoint of your application. Your endpoint must be accessible over the public internet.
Your endpoint must respond quickly to HTTPS requests. A response time over 5 seconds is considered a timeout and the delivery may be retried.
Webhooks
A webhook subscribes your endpoint to notifications for a set of event types.
A webhook can be disabled and re-enabled. When disabled, notifications will not be delivered to your endpoint.
When you create a webhook, you receive a random token. This token allows you to verify that POST requests to your endpoint originated from your webhook. You can also secure your webhook endpoints.
Webhook events
Webhook events are records of occurrences within your Foxglove organization.
A webhook event consists of a timestamp, an event type, and additional data about the event specific to that type.
| Event Type | Description |
|---|---|
recording.created | Occurs when a recording is created. For direct uploads, this occurs at the same time as recording.imported. Otherwise, this event occurs when an Edge Site or a device running the Foxglove Agent reports a new recording to Foxglove. |
recording.imported | Occurs when a recording finishes importing. |
device.created | Occurs when a new Device is added to your organization. |
event.created | Occurs when a new Event is added to your organization. |
ping | Ping event for debugging webhook endpoint connectivity. |
Notifications
A notification is what your webhook endpoint receives when an event occurs. Notifications are delivered as POST requests to your HTTPS endpoint. Notifications may be delivered more than once.
The HTTP request of a notification contains the signature in the header and the notification details in the body.
The full set expected notification payloads can be found in the API Reference.
Request headers
| key | value |
|---|---|
Content-Type | application/json |
fg-webhook-signature | A SHA256 HMAC digest of the entire request body bytes, with your webhook token as the secret. Used to verify the sender of the request. |
Request body
The request body is formatted as a JSON object, with some keys common to all event types others dependent on the event type. The full definition is available in the API reference.
Deliveries
A delivery is a record of an attempt to deliver a notification to your endpoint. Foxglove displays a recent history of successful and failed deliveries on the Webhook settings page.
Delivery semantics
Foxglove guarantees at-least-once delivery for webhook notifications. Each notification has a unique combination of webhookId and webhookEventId values. This can be used to de-duplicate deliveries of notifications received by your endpoint.
Either a non-response or a non-2xx HTTP status are considered failures. Failures will be automatically retried up to 5 times, with an increasing delay between attempts. You can use the Retry-After header on your endpoint's response to set a minimum bound on this delay time.
Admins can also manually retry failed deliveries. Manual retries disable the automatic retry mechanism for that notification.