Implementation

Code examples and best practices for implementing webhook handlers

Framework Examples

Choose your preferred framework to get started:

Express (Node.js)

import express from 'express';
import crypto from 'crypto';
import { WebhookHandler } from './handlers';

const app = express();

// Parse raw body for signature verification
app.use(express.json({
  verify: (req: any, res, buf) => {
    req.rawBody = buf;
  }
}));

app.post('/webhooks', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const webhookSecret = process.env.WEBHOOK_SECRET;
  
  // Verify signature
  const hmac = crypto.createHmac('sha256', webhookSecret);
  const computedSignature = hmac
    .update(req.rawBody)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  )) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process event asynchronously
  const event = req.body;
  
  try {
    // Acknowledge receipt quickly
    res.status(200).json({ received: true });
    
    // Process in background
    await WebhookHandler.processEvent(event);
  } catch (error) {
    console.error('Webhook processing error:', error);
  }
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Flask (Python)

from flask import Flask, request, jsonify
import hmac
import hashlib
import os
from webhook_handler import WebhookHandler

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    # Get signature and payload
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data()
    
    # Verify signature
    webhook_secret = os.environ.get('WEBHOOK_SECRET')
    computed = hmac.new(
        webhook_secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(computed, signature):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Process event asynchronously
    try:
        # Acknowledge receipt quickly
        response = jsonify({'received': True})
        
        # Process in background
        event = request.json
        WebhookHandler.process_event(event)
        
        return response, 200
    except Exception as e:
        print(f'Webhook processing error: {e}')
        return jsonify({'error': str(e)}), 500

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

Laravel (PHP)

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\WebhookHandler;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $signature = $request->header('X-Webhook-Signature');
        $payload = $request->getContent();
        
        // Verify signature
        $webhookSecret = env('WEBHOOK_SECRET');
        $computed = hash_hmac('sha256', $payload, $webhookSecret);
        
        if (!hash_equals($computed, $signature)) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }
        
        // Process event asynchronously
        try {
            // Acknowledge receipt quickly
            $response = response()->json(['received' => true]);
            
            // Process in background
            $event = json_decode($payload, true);
            WebhookHandler::processEvent($event);
            
            return $response;
        } catch (\Exception $e) {
            \Log::error('Webhook processing error: ' . $e->getMessage());
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}

Spring Boot (Java)

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Arrays;

@SpringBootApplication
@RestController
public class WebhookController {

    @PostMapping("/webhooks")
    public ResponseEntity<?> handleWebhook(
        @RequestHeader("X-Webhook-Signature") String signature,
        @RequestBody String payload
    ) {
        String webhookSecret = System.getenv("WEBHOOK_SECRET");

        try {
            // Verify signature
            Mac sha256Hmac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(
                webhookSecret.getBytes(StandardCharsets.UTF_8),
                "HmacSHA256"
            );
            sha256Hmac.init(secretKey);
            String computedSignature = bytesToHex(
                sha256Hmac.doFinal(payload.getBytes())
            );

            if (!MessageDigest.isEqual(
                computedSignature.getBytes(),
                signature.getBytes()
            )) {
                return ResponseEntity
                    .status(401)
                    .body(Map.of("error", "Invalid signature"));
            }

            // Process event asynchronously
            ObjectMapper mapper = new ObjectMapper();
            Map<String, Object> event = mapper.readValue(payload, Map.class);

            // Acknowledge receipt quickly
            CompletableFuture.runAsync(() -> {
                try {
                    WebhookHandler.processEvent(event);
                } catch (Exception e) {
                    log.error("Webhook processing error: " + e.getMessage());
                }
            });

            return ResponseEntity.ok(Map.of("received", true));
        } catch (Exception e) {
            log.error("Webhook error: " + e.getMessage());
            return ResponseEntity
                .status(500)
                .body(Map.of("error", e.getMessage()));
        }
    }

    private static String bytesToHex(byte[] hash) {
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    }

    public static void main(String[] args) {
        SpringApplication.run(WebhookController.class, args);
    }
}

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "encoding/json"
    "io/ioutil"
    "log"
    "net/http"
    "os"
)

type Response struct {
    Error    string `json:"error,omitempty"`
    Received bool   `json:"received,omitempty"`
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    // Get signature and payload
    signature := r.Header.Get("X-Webhook-Signature")
    payload, err := ioutil.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Failed to read body", http.StatusBadRequest)
        return
    }

    // Verify signature
    webhookSecret := os.Getenv("WEBHOOK_SECRET")
    mac := hmac.New(sha256.New, []byte(webhookSecret))
    mac.Write(payload)
    computedSignature := hex.EncodeToString(mac.Sum(nil))

    if subtle.ConstantTimeCompare(
        []byte(computedSignature),
        []byte(signature),
    ) != 1 {
        w.WriteHeader(http.StatusUnauthorized)
        json.NewEncoder(w).Encode(Response{
            Error: "Invalid signature",
        })
        return
    }

    // Process event asynchronously
    var event map[string]interface{}
    if err := json.Unmarshal(payload, &event); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(Response{
            Error: "Invalid JSON payload",
        })
        return
    }

    // Acknowledge receipt quickly
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(Response{
        Received: true,
    })

    // Process in background
    go func() {
        if err := processWebhook(event); err != nil {
            log.Printf("Webhook processing error: %v", err)
        }
    }()
}

func main() {
    http.HandleFunc("/webhooks", handleWebhook)
    log.Fatal(http.ListenAndServe(":3000", nil))
}

func processWebhook(event map[string]interface{}) error {
    // Implement your webhook processing logic here
    return nil
}

Event Handler Example

Here's an example of handling payment events:

class WebhookHandler {
  static async processEvent(event: WebhookEvent) {
    switch (event.type) {
      case 'subscription.created':
        await this.handleSubscriptionCreated(event.data);
        break;
      case 'subscription.updated':
        await this.handleSubscriptionUpdated(event.data);
        break;
      case 'transaction.created':
        await this.handleTransactionCreated(event.data);
        break;
      case 'transaction.updated':
        await this.handleTransactionUpdated(event.data);
        break;
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }
  }

  static async handleSubscriptionCreated(data: SubscriptionData) {
    // Update user's subscription status
    await db.subscriptions.create({
      userId: data.customerId,
      planId: data.planId,
      status: data.status,
      currentPeriodEnd: data.currentPeriodEnd
    });
  }

  // ... implement other handlers
}