Shernova delivers outbound webhooks when verification completes. Configure webhook_url on your app in the dashboard or via PATCH /v1/apps/:id.

Events

Delivery

Method: POST · Content-Type: application/json · Timeout: 10 seconds · Retries: up to 5 attempts with backoff [1s, 5s, 30s, 2m, 10m].

Headers

Content-Type: application/json
User-Agent: Shernova-Webhook/1.0
X-Shernova-Event: verification.completed
X-Shernova-Signature: sha256=<hmac_hex>

Payload (verification.completed)

{
  "session_id": "uuid",
  "status": "verified",
  "phone_number": "+201012345678",
  "verified_at": "2026-07-21T12:00:00.000Z",
  "timestamp": "2026-07-21T12:00:01.000Z"
}

Test payload

{
  "event": "webhook.test",
  "app_id": "uuid",
  "status": "test",
  "timestamp": "2026-07-21T12:00:00.000Z"
}

Verify signature

Compute HMAC-SHA256 of the raw request body using your webhook secret. Compare to X-Shernova-Signature (strip sha256= prefix).

const crypto = require('crypto');

function verify(body, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  const received = signatureHeader.replace(/^sha256=/, '');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

URL requirements

• HTTPS only (webhook_https_required)
• No private/reserved IPs (webhook_private_address)
• No redirects (webhook_redirect)
• Must respond with 2xx within 10 seconds

Monitoring

Admin portal /admin/webhooks shows delivery attempts. Failed deliveries can be retried via POST /v1/admin/webhooks/:id/retry.