How Webhooks Work
Real-time Events
Receive instant notifications when validation requests complete or important events occur.
Secure Delivery
HMAC-SHA256 signatures ensure webhook authenticity and prevent replay attacks.
Reliable Delivery
Automatic retries with exponential backoff ensure your webhooks are delivered.
Webhook Configuration
Set up your webhook endpoint in the dashboard
// Webhook endpoint configuration
{
"url": "https://your-app.com/webhooks/1lookup",
"events": [
"validation.phone.completed",
"validation.email.completed",
"tokens.low_balance"
],
"secret": "whsec_your_webhook_secret",
"active": true,
"headers": {
"X-Custom-Header": "optional-value"
}
}Configuration Options
- Multiple endpoints per organization
- Filter by specific event types
- Custom headers for authentication
- Enable/disable without deletion
Delivery Guarantees
- At-least-once delivery guarantee
- Automatic retries (3 attempts)
- Exponential backoff (1s, 5s, 30s)
- Event log for debugging
Available Events
validation.phone.completed
Triggered when a phone validation request is processed
Example Payload
{
"event": "validation.phone.completed",
"timestamp": "2024-01-15T10:30:00Z",
"webhook_id": "wh_1a2b3c4d5e6f",
"data": {
"request_id": "req_7g8h9i0j1k2l",
"phone": "+14155552671",
"validation_result": {
"valid": true,
"carrier": "Verizon Wireless",
"line_type": "mobile",
"fraud_score": 15,
"risk_level": "low"
},
"tokens_used": 3,
"api_key_id": "1lk_prod_abc123..."
}
}validation.email.completed
Triggered when an email validation request is processed
Example Payload
{
"event": "validation.email.completed",
"timestamp": "2024-01-15T10:31:00Z",
"webhook_id": "wh_2b3c4d5e6f7g",
"data": {
"request_id": "req_8h9i0j1k2l3m",
"email": "john.doe@example.com",
"validation_result": {
"valid": true,
"deliverable": true,
"disposable": false,
"fraud_score": 5
},
"tokens_used": 1,
"api_key_id": "1lk_prod_abc123..."
}
}spam.check.completed
Triggered when a spam check request is processed
Example Payload
{
"event": "spam.check.completed",
"timestamp": "2024-01-15T10:32:00Z",
"webhook_id": "wh_3c4d5e6f7g8h",
"data": {
"request_id": "req_9i0j1k2l3m4n",
"phone": "+14155552671",
"spam_result": {
"spam_score": 22,
"reputation": "Positive",
"robo_status": "Allowed",
"complaint_count": 0
},
"tokens_used": 2,
"api_key_id": "1lk_prod_abc123..."
}
}lookup.ip.completed
Triggered when an IP lookup request is processed
Example Payload
{
"event": "lookup.ip.completed",
"timestamp": "2024-01-15T10:33:00Z",
"webhook_id": "wh_4d5e6f7g8h9i",
"data": {
"request_id": "req_0j1k2l3m4n5o",
"ip": "192.168.1.1",
"lookup_result": {
"country": "United States",
"city": "San Francisco",
"vpn": false,
"proxy": false,
"fraud_score": 8
},
"tokens_used": 1,
"api_key_id": "1lk_prod_abc123..."
}
}tokens.low_balance
Triggered when token balance falls below configured threshold
Example Payload
{
"event": "tokens.low_balance",
"timestamp": "2024-01-15T10:34:00Z",
"webhook_id": "wh_5e6f7g8h9i0j",
"data": {
"organization_id": "org_abc123...",
"current_balance": 50,
"threshold": 100,
"plan": "Growth",
"auto_replenish_enabled": true
}
}tokens.replenished
Triggered when tokens are automatically replenished
Example Payload
{
"event": "tokens.replenished",
"timestamp": "2024-01-15T10:35:00Z",
"webhook_id": "wh_6f7g8h9i0j1k",
"data": {
"organization_id": "org_abc123...",
"tokens_added": 11000,
"bonus_tokens": 1000,
"new_balance": 11050,
"charge_amount": "$495.00"
}
}Security & Verification
Verify webhook authenticity using HMAC signatures
Webhook Headers
X-1Lookup-Signature: sha256=abc123...
X-1Lookup-Timestamp: 1642435200
X-1Lookup-Webhook-Id: wh_1a2b3c4d5e6f
// Node.js webhook verification example
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const hash = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return hash === signature;
}
// Express.js webhook handler
app.post('/webhooks/1lookup', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-1lookup-signature'];
const timestamp = req.headers['x-1lookup-timestamp'];
const webhookId = req.headers['x-1lookup-webhook-id'];
// Verify timestamp is within 5 minutes
const currentTime = Math.floor(Date.now() / 1000);
if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
return res.status(400).send('Timestamp too old');
}
// Verify signature
const payload = timestamp + '.' + req.body;
if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process webhook
const event = JSON.parse(req.body);
console.log('Received event:', event.event);
// Handle different event types
switch(event.event) {
case 'validation.phone.completed':
// Update your database with validation results
break;
case 'tokens.low_balance':
// Alert your team about low balance
break;
// ... handle other events
}
res.status(200).send('Webhook processed');
});Important Security Notes
- • Always verify webhook signatures in production
- • Check timestamp to prevent replay attacks (5-minute window)
- • Store webhook secrets securely (environment variables)
- • Use HTTPS endpoints only
Best Practices
Implementation Tips
- Process webhooks asynchronously using queues
- Return 200 OK immediately after receiving
- Handle duplicate events idempotently
- Log all webhook events for debugging
Error Handling
- Implement retry logic for failed processing
- Set up monitoring and alerting
- Have a manual reconciliation process
- Test webhook handlers thoroughly