Webhooks & Signature Verification
PingoLine pushes real-time HTTP POST notifications to your webhook URL whenever a call finishes or an SMS status updates.
Webhook Headers
Every webhook payload delivered by PingoLine includes the following security headers:
| Header | Description |
|---|---|
X-PingoLine-Event | Event identifier (e.g. order_call.completed) |
X-PingoLine-Delivery | Unique delivery UUID |
X-PingoLine-Signature | sha256=<HMAC-SHA256 hex digest of the raw body> |
Signature Verification
To ensure that the webhook genuinely originated from PingoLine and was not tampered with in transit:
- Retrieve the
X-PingoLine-Signatureheader. - Compute the HMAC-SHA256 hash of the raw request body string using your Webhook Secret as the key.
- Compare the calculated hash with the signature header using a timing-safe equality function.
Verification Examples
php
use PingoLine\Laravel\Facades\PingoLine;
use Illuminate\Http\Request;
Route::post('/webhooks/pingoline', function (Request $request) {
// Automatically verifies signature & throws WebhookVerificationException if invalid
$event = PingoLine::constructEventFromRequest($request);
if ($event->isOrderCallCompleted()) {
$orderId = $event->getOrderId();
if ($event->isConfirmed()) {
// Customer pressed 1 (Confirmed)
} elseif ($event->isCancelled()) {
// Customer pressed 2 (Cancelled)
}
}
return response()->json(['status' => 'ok']);
});typescript
import express from 'express';
import { PingoLine } from 'pingoline';
const app = express();
const pingoline = new PingoLine({
apiKey: process.env.PINGOLINE_API_KEY!,
webhookSecret: process.env.PINGOLINE_WEBHOOK_SECRET!,
});
// Preserve raw body for signature verification
app.post('/api/webhooks/pingoline', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-pingoline-signature'] as string;
const rawBody = req.body.toString('utf8');
try {
const event = pingoline.constructEvent(rawBody, signature);
if (event.isOrderCallCompleted()) {
const orderId = event.getOrderId();
if (event.isConfirmed()) {
// Customer confirmed order
}
}
return res.status(200).json({ received: true });
} catch (err) {
return res.status(403).json({ error: 'Signature verification failed' });
}
});Payload Schema (order_call.completed)
json
{
"id": "oc_8f7b2c9e",
"order_id": "ORD-1002",
"phone": "01712345678",
"status": "confirmed",
"dtmf_result": "confirmed",
"attempts": 1,
"duration_seconds": 19,
"created_at": "2026-11-21T14:30:00Z",
"updated_at": "2026-11-21T14:30:22Z"
}