Webhooks

Setting Up Webhooks

You can configure webhook endpoints in the Dashboard Settings. Owl Eyes will send a generic HTTP POST request to your configured URL whenever an event occurs.

Event Types

We currently support the following event types:

• verification.completed - Verification successfully finished (Result: Verified or Failed).
• verification.review_required - The verification was flagged for manual review.
• verification.expired - The verification link expired before completion.

Payload Format

Webhook payloads are sent as JSON. Here is an example of a verification.completed event:

{
  "event": "verification.completed",
  "created_at": "2024-12-25T10:00:00Z",
  "data": {
    "verification_id": "v_123456789",
    "status": "verified", // or 'failed'
    "score": 98,
    "metadata": {
      "user_id": "u_555"
    },
    "extracted_data": {
       "first_name": "Jane",
       "last_name": "Doe",
       "date_of_birth": "1990-01-01",
       "document_number": "A1234567"
    }
  }
}

Security & Verification

To verify that the webhook came from Owl Eyes, check the X-Owl-Signature header.

The signature is an HMAC-SHA256 hash of the request body, signed with your Webhook Secret (available in the Dashboard).

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return hash === signature;
}

Retry Behavior

If your endpoint returns a non-200 status code, we will retry the webhook delivery with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: +1 minute
• Attempt 3: +5 minutes
• Attempt 4: +15 minutes
• Attempt 5: +1 hour

After 5 failed attempts, we will stop sending that specific event.