Webhooks

• You must be on a paid plan to use webhooks
• Your server must be able to receive HTTPS requests
• You must have the Universal Verify backend SDK installed

1. Navigate to your integration settings in the Universal Verify dashboard
2. Under the "Webhooks" section, add your webhook endpoint URL
3. Save your webhook secret securely (you'll need it for signature verification)

user.verification.updated

Triggered when a user's verification status or confidence level changes.

Payload Structure

{
    "type": "user.verification.updated",
    "data": {
        "sub": "user_id",
        "verified": true,
        "verification_confidence": 3,
        "previous_values": {
            "verified": false,
            "verification_confidence": null
        }
    }
}

Security Considerations

• Always verify the webhook signature to ensure the request came from Universal Verify
• Store your webhook secret securely
• Use HTTPS for your webhook endpoint
• Implement proper error handling

Example Implementation

Here's an example of how to handle webhooks using AWS Lambda:

import UniversalVerify from 'universal-verify';

const webhookSecret = 'your-webhook-secret';
const universalVerifyClient = new UniversalVerify('client-id', 'client-secret');

exports.handler = async (event) => {
    try {
        // Get the signature from headers
        const signature = event.headers['Universal-Verify-Signature'] || 
                         event.headers['universal-verify-signature'];

        // Verify the webhook signature
        const body = universalVerifyClient.verifyWebhookSignature(
            event.body,
            signature,
            webhookSecret
        );

        // Process the webhook
        switch (body.type) {
            case 'user.verification.updated':
                await handleVerificationUpdate(body.data);
                break;
            // Add other event types as needed
        }

        return {
            statusCode: 200,
            body: JSON.stringify({
                status: 'Success',
                message: 'Webhook received'
            })
        };
    } catch (error) {
        console.error('Webhook error:', error);
        return {
            statusCode: 400,
            body: JSON.stringify({
                status: 'Error',
                message: 'Invalid webhook signature'
            })
        };
    }
};

• Respond to webhooks quickly (within 20 seconds)
• Implement idempotency to handle duplicate webhooks
• Log webhook events for debugging and auditing
• Have a fallback mechanism for failed webhook deliveries
• Monitor webhook delivery status

Delivery and Retries

If a webhook delivery fails (e.g., your server is down or returns an error), Universal Verify will retry the delivery up to 2 additional times, for a total of 3 attempts (including the initial delivery). Each retry attempt will be made with the same payload and signature.

Common Issues

• Invalid Signature: Ensure your webhook secret is correct and properly stored
• Timeout: Make sure your webhook handler responds within 20 seconds
• Duplicate Events: Implement idempotency to handle retries
• Missing Headers: Check that your server preserves the Universal-Verify-Signature header