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

EventDescription
company.createdA new company was created.
company.updatedCompany details changed.
company.suspendedA company was suspended.
company.deletedA company was deleted.
user.createdA new user was created.
user.updatedUser details changed.
user.deletedA user was deleted.
training.assignedTraining was assigned to users.
training.completedA user completed training.
training.overdueA training assignment became overdue.
seats.limit_reachedA company reached its hard seat limit.
seats.limit_exceededA company exceeded its soft seat limit.
seats.pool_lowThe reseller seat pool dropped below 20%.
governance.report-readyA scheduled governance report was generated and delivered.
governance.summaryA 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.