> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v1.latitude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn how to receive real-time notifications about events that occur in your Latitude workspace.

## Overview

Webhooks provide a way to integrate Latitude with your own systems and applications.
When an event occurs, Latitude will send an HTTP POST request to your configured webhook URL with details about the event.

Currently, webhooks support notifications for commit publications, with more event types coming soon.

## Setting Up Webhooks

### Creating a Webhook

1. Navigate to your workspace [settings](https://app.latitude.so/settings)
2. Go to the **Webhooks** section
3. Click **New Webhook**
4. 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.

<Note>
  The `X-Latitude-Signature` header is **not** included when testing the
  endpoint using the "Test Endpoint" button from the Latitude UI.
</Note>

## Webhook Events

Currently, Latitude webhooks support the following event:

### Project Events

* `commitPublished`: Triggered when a commit is published in a project
* `documentLogCreated`: Triggered when a prompt log is created 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:

1. HTTP Headers:

   ```
   X-Latitude-Signature: <signature>
   ```

2. Request Body:
   ```json theme={null}
   {
     "eventType": "commitPublished",
     "payload": {
       // Commit-specific data
     }
   }
   ```

## Webhook Delivery

Latitude implements a robust webhook delivery system:

1. **Retry Logic**: Failed webhook deliveries are automatically retried with exponential backoff
2. **Delivery Status**: You can monitor webhook delivery status in the webhook settings (upcoming)
3. **Error Handling**: Failed deliveries include error messages and response status codes
4. **Rate Limiting**: Webhook requests are rate-limited to prevent overwhelming your servers

## Best Practices

1. **Verify Signatures**: Always verify webhook signatures to ensure requests are from Latitude
2. **Handle Duplicates**: Implement idempotency checks to handle duplicate webhook deliveries
3. **Respond Quickly**: Respond to webhook requests within 5 seconds
4. **Monitor Failures**: Regularly check webhook delivery status and logs
5. **Use HTTPS**: Always use HTTPS endpoints for webhook URLs
6. **Whitelisting**: Whitelist Latitude IP addresses to ensure delivery
7. **IP Addresses**:
   * 18.193.205.15

## Example Implementation

Here's an example of how to verify a webhook signature in Node.js:

```javascript theme={null}
const crypto = require('crypto')

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  const calculatedSignature = hmac.update(payload).digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(calculatedSignature),
  )
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // Process the webhook
  res.status(200).send('OK')
})
```

## Troubleshooting

If you're experiencing issues with webhooks:

1. Check the webhook delivery status in your workspace settings
2. Verify your webhook URL is accessible and responding correctly
3. Ensure your server is handling requests within the timeout period
4. Check your server logs for any errors
5. Verify the webhook signature is being calculated correctly