Webhooks
Webhooks notify your integration when important reseller account or company governance events happen.
Setting Up Webhooks
Configure reseller webhooks in Settings > Webhooks. Configure company governance webhooks in Email Security > Governance & Reports. Use HTTPS, select the events to receive, and set a signing secret.
Webhook Payload
{
"id": "evt_abc123",
"type": "company.created",
"created_at": "2026-01-25T10:30:00Z",
"data": {}
}Verifying Webhooks
Each governance webhook request includes X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-Delivery, and X-Webhook-Event headers. Compute an HMAC SHA-256 signature over timestamp.delivery_id.event.raw_body with your webhook secret, prefix it with sha256=, reject stale timestamps, and compare with a timing-safe check.
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$delivery = $_SERVER['HTTP_X_WEBHOOK_DELIVERY'];
$event = $_SERVER['HTTP_X_WEBHOOK_EVENT'];
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';
if (abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$base = $timestamp.'.'.$delivery.'.'.$event.'.'.$payload;
$expected = 'sha256='.hash_hmac('sha256', $base, $secret);
if (! hash_equals($expected, $signature)) {
http_response_code(401);
exit;
}Available Events
| Event | Description |
|---|---|
| company.created | A new company was created. |
| company.updated | Company details changed. |
| company.suspended | A company was suspended. |
| company.deleted | A company was deleted. |
| user.created | A new user was created. |
| user.updated | User details changed. |
| user.deleted | A user was deleted. |
| training.assigned | Training was assigned to users. |
| training.completed | A user completed training. |
| training.overdue | A training assignment became overdue. |
| seats.limit_reached | A company reached its hard seat limit. |
| seats.limit_exceeded | A company exceeded its soft seat limit. |
| seats.pool_low | The reseller seat pool dropped below 20%. |
| governance.report-ready | A scheduled governance report was generated and delivered. |
| governance.summary | A governance summary payload was requested or sent. |
Governance Webhook Payload
{
"event": "governance.report-ready",
"generated_at": "2026-05-16T08:00:00Z",
"company": {"id": 42, "name": "Example Ltd"},
"report": {
"mode": "cyber_insurance",
"report_period": {"from": "2026-04-16", "to": "2026-05-16"},
"summary": {"governance_score": 88, "open_threats": 2},
"controls": [{"id": "email_authentication", "status": "passed", "score": 92}],
"unavailable": []
},
"meta": {"schedule_id": 10, "format": "pdf"}
}Governance webhook failures are logged on the endpoint. Network errors, 408, 409, 425, 429, and 5xx responses are retried. Other 4xx responses are treated as terminal failures.
Retry Policy
- 1st retry: 5 minutes after the initial attempt.
- 2nd retry: 15 minutes after the 1st retry.
- 3rd retry: 1 hour after the 2nd retry.
- 4th retry: 4 hours after the 3rd retry.
- 5th retry: 24 hours after the 4th retry.
After the fifth retry fails, no more automatic retries are attempted.
Best Practices
- Return a 2xx response within 30 seconds.
- Process heavy work asynchronously.
- Use X-Webhook-Delivery to prevent duplicate processing.
- Always verify the webhook signature.
- Use HTTPS for every endpoint.