Skip to main content
Webhooks allow your application to receive real-time HTTP notifications when events occur in ezyshield. Instead of polling the API, you subscribe to specific events and ezyshield pushes updates to your endpoint.

​
Event types

Subscribe to any of the following verification events:
EventDescription
verification.pendingA verification has been created and is in progress.
verification.verifiedThe verification completed successfully.
verification.rejectedThe contact person rejected the verification.
verification.failedezyshield was unable to verify the details provided.
verification.cancelledThe verification was cancelled by a newer verification.
verification.expiredThe verification expired before completion.
verification.errorThe verification encountered an unexpected error.
verification.confirmation_notification_sentThe SMS notification was sent to the contact person.

​
Webhook Subscription object

A webhook subscription defines which events to receive and where to send them.
FieldTypeDescription
idstringUnique identifier for the subscription.
urlstringThe HTTPS endpoint where events are delivered.
eventsarrayList of event types to subscribe to.
created_attimestampWhen the subscription was created.
Example
{
  "id": "wh_sub_abc123",
  "url": "https://example.com/webhooks/ezyshield",
  "events": [
    "verification.verified",
    "verification.failed"
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

​
Webhook Event object

When an event occurs, ezyshield sends an HTTP POST request to your endpoint with the following payload:
FieldTypeDescription
idstringUnique identifier for the event.
typestringThe event type (e.g., verification.verified).
created_attimestampWhen the event occurred.
dataobjectThe Verification object associated with the event.
Example
{
  "id": "wh_evt_xyz789",
  "type": "verification.verified",
  "created_at": "2024-01-15T10:35:00Z",
  "data": {
    "id": "ver_abc123",
    "status": "verified",
    // ... full Verification object
  }
}

​
Verifying signatures

Every webhook request includes a Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature to ensure the request originated from ezyshield. 
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'];

$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
Always use constant-time comparison (e.g., hash_equals in PHP, hmac.compare_digest in Python) to prevent timing attacks.

​
Retry behavior

ezyshield expects a 2xx response within 3 seconds. If your endpoint fails to respond or returns a non-2xx status, ezyshield retries with exponential backoff:
AttemptDelay
1Immediate
210 seconds
3100 seconds
After 3 failed attempts, the event is marked as failed and no further retries occur.
If 10 consecutive events fail to deliver, ezyshield automatically disables the webhook subscription. You’ll need to fix the issue and re-enable the subscription to resume delivery.

​
Best practices

Return a 2xx response as soon as you receive the webhook. Process the event asynchronously to avoid timeouts.
app.post('/webhooks', (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhookAsync(req.body);
});
ezyshield delivers each event exactly once on success. However, if your endpoint fails and ezyshield retries, the retry will have the same event id. Use this ID to ensure idempotent processing and avoid duplicate side effects.
ezyshield only delivers webhooks to HTTPS endpoints. HTTP URLs are rejected when creating a subscription.
Always verify the Signature header before processing events to ensure requests originate from ezyshield.