Webhooks

Receive real-time notifications when verification jobs complete or other events occur in your RocketVerifier account.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events happen in RocketVerifier. Instead of polling our API, you receive instant notifications as soon as events occur.

Webhook Events

job.completed

Sent when a batch verification job finishes successfully.

job.failed

Sent when a batch verification job fails.

credits.low

Sent when your credit balance falls below the configured threshold.

credits.depleted

Sent when your credits reach zero.

Payload Format

All webhook payloads follow this structure:

job.completed

{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:32:15Z",
  "data": {
    "job_id": "job_abc123xyz",
    "name": "My Email List",
    "status": "completed",
    "total_emails": 1000,
    "valid_count": 850,
    "invalid_count": 100,
    "risky_count": 40,
    "unknown_count": 10,
    "download_url": "https://api.rocketverifier.com/v1/jobs/job_abc123xyz/download",
    "completed_at": "2024-01-15T10:32:15Z"
  }
}

Security

Signature Verification

Every webhook request includes an X-RocketVerifier-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing webhooks.

Node.js Verification

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhooks/rocketverifier', (req, res) => {
  const signature = req.headers['x-rocketverifier-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
  res.status(200).json({ received: true });
});

Retry Policy

If your endpoint returns a non-2xx status code, we'll retry the webhook with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry (final)	24 hours

Important: After 5 failed attempts, the webhook will be marked as failed and the endpoint may be automatically disabled.

Best Practices

Respond quickly

Return a 200 response within 5 seconds. Process webhooks asynchronously.

Handle duplicates

Use the event ID to deduplicate webhooks in case of retries.

Verify signatures

Always verify the webhook signature to ensure authenticity.

Use HTTPS

Your webhook endpoint must use HTTPS for security.

Configure Webhooks

Set up your webhook endpoints in the dashboard.

Go to Webhook Settings