Webhooks API
Receive real-time HTTP POST notifications when events occur in Unkept.
Quick Start
- Generate an API token from your account settings
- Create a webhook endpoint that accepts POST requests
- Register your webhook via the API or dashboard
- Implement signature verification for security
- Start receiving events!
Available Events
| Event | Description |
|---|---|
promise.created
|
A new promise is published |
promise.updated
|
Promise details are updated |
promise.status_changed
|
Promise verdict changes (kept/broken/etc.) |
promise.deadline_approaching
|
Promise deadline is approaching (30/7/1 days) |
promise.expired
|
Promise deadline has passed |
person.created
|
A new person is added to the database |
person.updated
|
Person details are updated |
company.created
|
A new company is added |
company.updated
|
Company details are updated |
Payload Format
{
"event": "promise.status_changed",
"occurred_at": "2026-01-30T10:00:00.000000Z",
"api_version": "v1",
"data": {
"promise": {
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"slug": "example-promise",
"title": "Example Promise Title",
"status": "broken",
"url": "https://unkept.io/promises/example-promise"
},
"person": {
"slug": "john-doe",
"name": "John Doe",
"type": "ceo"
},
"old_status": "pending",
"new_status": "broken"
}
}Signature Verification
Every webhook request includes headers for verification. Always verify signatures to ensure requests are authentic.
Important: Always verify webhook signatures before processing requests.
Headers
| Header | Description |
|---|---|
X-Webhook-Signature |
HMAC-SHA256 signature |
X-Webhook-Timestamp |
Unix timestamp |
X-Webhook-Version |
API version (v1) |
Verification Examples
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
$valid = hash_equals($expected, $signature);Subscription Limits
| Tier | Webhooks | Connectors |
|---|---|---|
| Free | 0 | 0 |
| Pro | 2 | 5 |
| Journalist | 5 | 10 |
| Enterprise | 50 | Unlimited |
Retry Policy
Failed deliveries are automatically retried with exponential backoff:
- 30 seconds
- 2 minutes
- 8 minutes
- 32 minutes
- 2 hours
After 5 failed attempts, the delivery is marked as permanently failed. Webhooks are automatically disabled after 10 consecutive failures.
Third-Party Connectors
In addition to custom webhooks, we offer pre-built connectors for popular platforms:
Slack
Post notifications to Slack channels
Discord
Send updates to Discord servers
Microsoft Teams
Post to Teams channels
Zapier
Trigger automated workflows
Generic
Custom HTTP endpoints
API Reference
For complete API documentation, see the full reference: