Skip to content

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:

HeaderDescription
X-PingoLine-EventEvent identifier (e.g. order_call.completed)
X-PingoLine-DeliveryUnique delivery UUID
X-PingoLine-Signaturesha256=<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:

  1. Retrieve the X-PingoLine-Signature header.
  2. Compute the HMAC-SHA256 hash of the raw request body string using your Webhook Secret as the key.
  3. 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"
}

Released under the MIT License.