Skip to main content
Your app creates a verification. ezyshield sends events as it progresses. Your app updates local state when the verification reaches a terminal status. Polling is useful while debugging. In production, prefer webhooks.

​
Events to subscribe to

At minimum, subscribe to the terminal verification events:
EventMeaning
verification.successfulThe verification completed successfully.
verification.rejectedThe contact rejected the verification.
verification.failedezyshield could not verify the supplied details.
verification.cancelledThe verification was cancelled or superseded.
verification.expiredThe contact did not complete the flow in time.
verification.errorAn unexpected error occurred.
You may also subscribe to progress events:
EventMeaning
verification.pendingThe verification is in progress.
verification.confirmation_readyThe contact confirmation step is ready.
verification.confirmation_notification_sentezyshield sent the contact notification.
1

Verify the signature

Verify the webhook signature before processing the body. ezyshield signs outbound webhooks with the subscription secret returned when the subscription is created.
2

Record the event ID

Store processed event IDs. If ezyshield retries a delivery, your app can safely ignore the duplicate side effects.
3

Update local verification state

Use the verification ID in the event data to update the record in your system. Store the latest status and event timestamp.
4

Respond quickly

Return a 2xx response once the event is accepted. Do slower work asynchronously.

​
Signature verification

By default, ezyshield sends the HMAC-SHA256 signature in the Signature header. Verify the signature against the raw request body before parsing or mutating the payload. 
$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');
}
Use the raw request body for signature verification and compare signatures in constant time. Re-serializing parsed JSON can change the bytes being signed.
Store the webhook subscription secret when the subscription is created. The secret is only returned in the create response.

​
Idempotency pattern

Webhook delivery can be retried. Your handler should be safe to run more than once for the same event. 
receive event
  -> verify signature
  -> check whether event ID was already processed
  -> store event ID
  -> update verification state
  -> return 2xx

​
Managing subscriptions

Create and manage webhook subscriptions from the Dashboard or through the API. API management requires webhook_subscription:read and webhook_subscription:write; receiving webhook deliveries does not require those abilities on the key that created the verification. For subscription fields and event types, see Webhooks.