How to receive Helcim webhooks on your website

<?php

// Retrieve the raw POST body BEFORE reading $_POST
$payload = file_get_contents('php://input');

// Your signing secret (store in an environment variable)
$secret = getenv('ZORVEQ_WEBHOOK_SECRET');

// Extract the signature header
$sigHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

// Compute expected signature
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

// Reject if signature does not match
if (!hash_equals($expected, $sigHeader)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Decode the event
$event = json_decode($payload, true);
$eventType = $event['eventType'] ?? $event['type'] ?? 'unknown';

switch ($eventType) {
    case 'payment.success':
        // handle successful payment
        $amount    = $event['data']['amount'] ?? null;
        $invoiceId = $event['data']['invoiceNumber'] ?? null;
        // ... your logic here
        break;

    case 'payment.failed':
        // handle failed payment
        break;

    case 'refund.success':
        // handle refund
        break;

    default:
        // unknown event — log and ignore
        break;
}

// Respond 200 quickly so the router marks the delivery as successful
http_response_code(200);
echo json_encode(['status' => 'ok']);

const express = require('express');
const crypto  = require('crypto');
const router  = express.Router();

// Your signing secret (store in an environment variable)
const SECRET = process.env.ZORVEQ_WEBHOOK_SECRET;

// IMPORTANT: use express.raw() so we get the unmodified body bytes for signature verification
router.post('/webhooks/inbound', express.raw({ type: 'application/json' }), (req, res) => {
  const sigHeader = req.headers['x-webhook-signature'] || '';
  const expected  = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(req.body)       // req.body is a Buffer when using express.raw()
    .digest('hex');

  // Reject if signature does not match
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sigHeader))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  const eventType = event.eventType || event.type || 'unknown';

  switch (eventType) {
    case 'payment.success':
      // handle successful payment
      console.log('Payment received:', event.data);
      break;

    case 'payment.failed':
      // handle failed payment
      break;

    case 'refund.success':
      // handle refund
      break;

    default:
      console.log('Unhandled event type:', eventType);
  }

  // Respond 200 quickly
  res.status(200).json({ status: 'ok' });
});

module.exports = router;

import hashlib
import hmac
import os
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()

# Your signing secret (store in an environment variable)
SECRET = os.environ["ZORVEQ_WEBHOOK_SECRET"]


@app.post("/webhooks/inbound")
async def receive_webhook(
    request: Request,
    x_webhook_signature: str = Header(...),
):
    body = await request.body()

    # Compute expected signature
    expected = "sha256=" + hmac.new(
        SECRET.encode(), body, hashlib.sha256
    ).hexdigest()

    # Reject if signature does not match
    if not hmac.compare_digest(expected, x_webhook_signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    event_type = event.get("eventType") or event.get("type") or "unknown"

    if event_type == "payment.success":
        # handle successful payment
        pass
    elif event_type == "payment.failed":
        # handle failed payment
        pass
    elif event_type == "refund.success":
        # handle refund
        pass

    # Respond 200 quickly
    return {"status": "ok"}

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class HelcimWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Read raw body before Laravel parses it
        $payload   = $request->getContent();
        $secret    = config('services.zorveq.webhook_secret'); // env('ZORVEQ_WEBHOOK_SECRET')
        $sigHeader = $request->header('X-Webhook-Signature', '');

        // Compute expected signature
        $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

        // Reject if signature does not match
        if (!hash_equals($expected, $sigHeader)) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }

        $event     = json_decode($payload, true);
        $eventType = $event['eventType'] ?? $event['type'] ?? 'unknown';

        match ($eventType) {
            'payment.success' => $this->handlePaymentSuccess($event),
            'payment.failed'  => $this->handlePaymentFailed($event),
            'refund.success'  => $this->handleRefund($event),
            default           => Log::info('Unhandled Helcim event', ['type' => $eventType]),
        };

        return response()->json(['status' => 'ok']);
    }

    private function handlePaymentSuccess(array $event): void
    {
        $amount    = $event['data']['amount']        ?? null;
        $invoiceId = $event['data']['invoiceNumber'] ?? null;
        // ... your logic here
    }

    private function handlePaymentFailed(array $event): void
    {
        // ... your logic here
    }

    private function handleRefund(array $event): void
    {
        // ... your logic here
    }
}

// In routes/api.php:
// Route::post('/webhooks/inbound', [HelcimWebhookController::class, 'handle'])
//      ->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);