Webhooks
Webhooks
Webhooks allow you to receive real-time notifications about events that occur in your Latitude workspace. When an event occurs, Latitude will send an HTTP POST request to your configured webhook URL with details about the event.
Overview
Webhooks provide a way to integrate Latitude with your own systems and applications. Currently, webhooks support notifications for commit publications, with more event types coming soon.
Setting Up Webhooks
Creating a Webhook
- Navigate to your workspace settings
- Go to the “Webhooks” section
- Click “New Webhook”
- Configure your webhook:
- Name: A descriptive name for your webhook
- URL: The endpoint where you want to receive webhook notifications
- Projects: (Optional) Filter events to specific projects
- Active: Enable/disable the webhook
Security
Each webhook is assigned a unique secret key that is used to sign webhook payloads. This allows you to verify that webhook requests are coming from Latitude.
When you receive a webhook request, you can verify its authenticity by checking the X-Latitude-Signature
header. The signature is generated using HMAC SHA-256 with your webhook’s secret key.
The X-Latitude-Signature
header is not included when testing the
endpoint using the “Test Endpoint” button from the Latitude UI.
Webhook Events
Currently, Latitude webhooks support the following event:
Project Events
commitPublished
: Triggered when a commit is published in a project
More event types will be added in future updates, including:
- Document runs and evaluations
- Project and workspace changes
- User management events
- Dataset operations
Webhook Payload
Each webhook request includes:
-
HTTP Headers:
-
Request Body:
Webhook Delivery
Latitude implements a robust webhook delivery system:
- Retry Logic: Failed webhook deliveries are automatically retried with exponential backoff
- Delivery Status: You can monitor webhook delivery status in the webhook settings (upcoming)
- Error Handling: Failed deliveries include error messages and response status codes
- Rate Limiting: Webhook requests are rate-limited to prevent overwhelming your servers
Best Practices
- Verify Signatures: Always verify webhook signatures to ensure requests are from Latitude
- Handle Duplicates: Implement idempotency checks to handle duplicate webhook deliveries
- Respond Quickly: Respond to webhook requests within 5 seconds
- Monitor Failures: Regularly check webhook delivery status and logs
- Use HTTPS: Always use HTTPS endpoints for webhook URLs
- Whitelisting: Whitelist Latitude IP addresses to ensure delivery
- IP Addresses:
- 18.193.205.15
Example Implementation
Here’s an example of how to verify a webhook signature in Node.js:
Troubleshooting
If you’re experiencing issues with webhooks:
- Check the webhook delivery status in your workspace settings
- Verify your webhook URL is accessible and responding correctly
- Ensure your server is handling requests within the timeout period
- Check your server logs for any errors
- Verify the webhook signature is being calculated correctly