Receive verification events without continuously polling.
Configure secure HTTP webhook destinations to receive real-time notifications for job progress, completion, failure, and wallet balance events with HMAC-SHA256 signature verification.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const WEBHOOK_SECRET = process.env.PHONEVERIFLO_WEBHOOK_SECRET;
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-phoneveriflo-signature'];
const timestamp = req.headers['x-phoneveriflo-timestamp'];
const rawBody = req.body.toString('utf8');
// Verify HMAC-SHA256 signature
const expectedSig = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig))) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(rawBody);
console.log(`Received event: ${event.type} for job: ${event.data.jobId}`);
res.status(200).json({ received: true });
});All requests require Bearer authorization with high-entropy secret tokens.
Bearer pv_live_...→Prevent duplicate jobs and safe automatic retries using 24h unique keys.
Idempotency-Key: uuid→Predictable Token Bucket model at 100 req/s with standard Retry-After headers.
100 req/s burst→Strict date-based compatibility guarantees with 12-month deprecation windows.
v1 (2026-08-11)→Test API Requests in Real Time
Build and simulate verification requests directly in your browser. Generates live code snippets and previews the exact response schema.
Configure request parameters and click Send Request to preview live execution.
Supported Webhook Event Types
Event CatalogSubscribe to lifecycle events relevant to your operational pipeline.
When configuring a webhook in the Developer Center (/app/developers), choose the event types you want delivered: job.created, job.verifying, job.completed, job.partial, job.failed, wallet.low_balance.
HMAC-SHA256 Webhook Signature Tester
Test and inspect webhook signature calculation in your browser to verify anti-tamper security.
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7819467b28const expected = crypto
.createHmac('sha256', 'whsec_9f82a1b4c3d2e5f6')
.update(timestamp + '.' + rawBody)
.digest('hex');
const valid = crypto.timingSafeEqual(
Buffer.from(headerSig),
Buffer.from(expected)
);Common Integration Questions
What IP addresses do webhooks originate from?
In production, webhooks originate from dedicated static egress IPs published in the Developer Center. However, we mandate validating the HMAC-SHA256 signature as your primary cryptographic security barrier.
Related Guides & API References
Ready to build with phoneveriflo?
Generate your secret API key in 30 seconds. Test preflight quotes and receive provider-neutral results with full freshness auditability.