What Are Webhooks?
Webhooks push notifications to your systems when events occur:
- Audit completed
- BPI score changed
- Hallucination detected
- Alert triggered
Instead of polling the API, you receive instant notifications.
Setting Up Webhooks
1. Go to **Settings > Webhooks**
2. Click **"Add Endpoint"**
3. Enter your endpoint URL
4. Select events to receive
5. Save
VectorGap will send a test request to verify your endpoint.
Event Types
Available webhook events:
**audit.completed**
Fired when any audit finishes.
**score.changed**
Fired when BPI changes by threshold amount.
**hallucination.detected**
Fired when new hallucination is found.
**alert.triggered**
Fired when any alert condition is met.
**competitor.changed**
Fired when competitor scores change significantly.
Payload Format
Webhooks send JSON payloads:
```json
{
"event": "audit.completed",
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"auditId": "aud_123",
"brandId": "brd_456",
"bpiScore": 72,
"previousScore": 68
}
}
```
Full payload schemas are documented in the API reference.
Handling Webhooks
Best practices:
- **Return 200 quickly** - Process async if needed
- **Verify signatures** - We sign payloads with your webhook secret
- **Handle retries** - Failed deliveries retry 3 times
- **Log everything** - Keep records for debugging
- **Idempotency** - Handle duplicate deliveries gracefully