Example Webhooks

This page contains example code for implementing webhooks in your application using Harlyy.

When an event occurs that triggers a webhook, our system sends an HTTP POST request to your configured endpoint. The request body contains an event object, and the request headers include X-Harlyy-Signature for verification using your webhook secret.

warning

Always verify the signature of incoming webhook requests to ensure they are from Harlyy and not forged by a third party. Use a secure method to store your webhook secret and never expose it in client-side code.

We always sign webhook requests using HMAC with SHA-256, and the signature is included in the X-Harlyy-Signature header. The signature is a base64-encoded HMAC of the request body using your webhook secret.

NodeJS

NodeJS Example

const express = require('express');
const crypto = require('crypto');
const app = express();

// Middleware to store raw body for HMAC verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

// Your shared webhook secret (store securely in real applications)
const WEBHOOK_SECRET = 'xxxxx';

function verifySignature(req) {
  const signatureHeader = req.headers['x-harlyy-signature'];

  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
    return false;
  }

  const receivedSignature = signatureHeader.slice(7); // Remove 'sha256='

  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  hmac.update(req.rawBody);
  const expectedSignature = hmac.digest('base64');

  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'utf8'),
    Buffer.from(receivedSignature, 'utf8')
  );
}

app.post('/webhook', (req, res) => {
  if (!verifySignature(req)) {
    console.log('❌ Invalid signature');
    return res.status(401).send('Invalid signature');
  }

  console.log('✅ Valid webhook received:', req.body);
  res.status(200).send('Webhook accepted');
});

const PORT = 3000;
  app.listen(PORT, () => {
  console.log(`🚀 Webhook listener running on http://localhost:${PORT}`);
});

Python

Python Example

from flask import Flask, request, abort
import hmac
import hashlib
import base64

app = Flask(__name__)

# Your shared webhook secret (store securely in real applications)
WEBHOOK_SECRET = 'xxxxx'

def verify_signature(req):
    signature_header = req.headers.get('X-Harlyy-Signature')
    if not signature_header or not signature_header.startswith('sha256='):
        return False

    received_signature = signature_header[7:]  # Remove 'sha256='
    hmac_digest = hmac.new(WEBHOOK_SECRET.encode(), req.data, hashlib.sha256).digest()
    expected_signature = base64.b64encode(hmac_digest).decode()

    return hmac.compare_digest(expected_signature, received_signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    if not verify_signature(request):
        print('❌ Invalid signature')
        abort(401)

    print('✅ Valid webhook received:', request.json)
    return 'Webhook accepted', 200

if __name__ == '__main__':
    app.run(port=3000)

PHP

PHP Example

require __DIR__ . '/vendor/autoload.php';

use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

$app = AppFactory::create();

define('WEBHOOK_SECRET', 'xxxxx');

// Middleware to capture raw body
$app->addBodyParsingMiddleware();
$app->add(function (Request $request, $handler) {
    $body = (string) $request->getBody();
    $request = $request->withAttribute('rawBody', $body);
    return $handler->handle($request);
});

$app->post('/webhook', function (Request $request, $response, $args) {
    $headers = $request->getHeaders();
    $signatureHeader = $headers['x-harlyy-signature'][0] ?? '';

    if (!preg_match('/^sha256=/', $signatureHeader)) {
        $response->getBody()->write('Invalid signature format');
        return $response->withStatus(401);
    }

    $receivedSignature = substr($signatureHeader, 7); // Strip 'sha256='
    $rawBody = $request->getAttribute('rawBody');

    // Generate expected HMAC signature
    $expectedSignature = base64_encode(hash_hmac('sha256', $rawBody, WEBHOOK_SECRET, true));

    // Constant-time comparison
    if (!hash_equals($expectedSignature, $receivedSignature)) {
        error_log('❌ Invalid signature');
        $response->getBody()->write('Invalid signature');
        return $response->withStatus(401);
    }

    $parsedBody = $request->getParsedBody();
    error_log('✅ Valid webhook received: ' . json_encode($parsedBody));
    $response->getBody()->write('Webhook accepted');
    return $response->withStatus(200);
});

$app->run();