Verification des signatures webhook

Chaque requete webhook inclut une signature cryptographique pour que vous puissiez verifier qu’elle provient bien d’Allo. Sans verification, un attaquant pourrait envoyer de faux evenements a votre endpoint.

En-tetes de signature

Chaque requete POST webhook inclut trois en-tetes :

En-tete	Description	Exemple
`webhook-id`	Identifiant unique du message	`msg_2NfDKEm9sF8xK3pQr1Zt`
`webhook-timestamp`	Horodatage Unix (secondes) de l’envoi du message	`1710510600`
`webhook-signature`	Une ou plusieurs signatures HMAC-SHA256	`v1,K5oZfzN95Z3M+nrYOgGHfLGC7t8VjLtV...`

Secret de signature

Lorsque vous creez un endpoint webhook, la reponse inclut un champ signing_secret. Ce secret a le format whsec_<base64key> et est utilise pour verifier les signatures. Stockez-le de maniere securisee — traitez-le comme un mot de passe. S’il est compromis, effectuez une rotation via l’API.

Algorithme de verification

Extraire les en-tetes

Recuperez webhook-id, webhook-timestamp et webhook-signature depuis les en-tetes de la requete.

Valider l'horodatage

Rejetez les requetes dont l’horodatage est eloigne de plus de 5 minutes de l’heure actuelle de votre serveur. Cela empeche les attaques par rejeu.

Construire le contenu signe

Concatenez l’identifiant du webhook, l’horodatage et le corps brut de la requete avec des points :

{webhook-id}.{webhook-timestamp}.{raw_body}

Calculer la signature attendue

Supprimez le prefixe whsec_ de votre secret de signature.
Decodez en base64 la chaine restante pour obtenir les octets de la cle.
Calculez le HMAC-SHA256 du contenu signe avec les octets de la cle.
Encodez le resultat en base64.

Comparer les signatures

L’en-tete webhook-signature peut contenir plusieurs signatures separees par des espaces (pour la rotation des secrets). Chacune a un prefixe v1,. Comparez votre signature calculee avec chacune d’entre elles. Si l’une correspond, la signature est valide.

Utilisez toujours le corps brut de la requete pour la verification. Si votre framework parse le JSON et le re-serialise, la signature ne correspondra pas.

Exemples de code

Node.js
Python
Go

const crypto = require("crypto");

function verifyWebhook(payload, headers, secret) {
  const webhookId = headers["webhook-id"];
  const webhookTimestamp = headers["webhook-timestamp"];
  const webhookSignature = headers["webhook-signature"];

  // Validate timestamp (5-minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(webhookTimestamp)) > 300) {
    throw new Error("Timestamp too old");
  }

  // Build signed content
  const signedContent = `${webhookId}.${webhookTimestamp}.${payload}`;

  // Decode secret (strip "whsec_" prefix, base64-decode)
  const secretBytes = Buffer.from(secret.split("_")[1], "base64");

  // Compute HMAC-SHA256
  const computed = crypto
    .createHmac("sha256", secretBytes)
    .update(signedContent)
    .digest("base64");

  // Compare against each signature in the header
  const signatures = webhookSignature
    .split(" ")
    .map((sig) => sig.split(",")[1]);

  if (!signatures.some((sig) => sig === computed)) {
    throw new Error("Invalid signature");
  }

  return JSON.parse(payload);
}

// Express.js example
const express = require("express");
const app = express();

app.post(
  "/webhooks/allo",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const event = verifyWebhook(
        req.body.toString(),
        req.headers,
        process.env.WEBHOOK_SECRET
      );
      console.log("Verified event:", event.topic);
      res.sendStatus(200);
    } catch (err) {
      console.error("Verification failed:", err.message);
      res.sendStatus(400);
    }
  }
);

import hmac
import hashlib
import base64
import time
import json

def verify_webhook(payload: bytes, headers: dict, secret: str) -> dict:
    webhook_id = headers.get("webhook-id")
    webhook_timestamp = headers.get("webhook-timestamp")
    webhook_signature = headers.get("webhook-signature")

    # Validate timestamp (5-minute tolerance)
    now = int(time.time())
    if abs(now - int(webhook_timestamp)) > 300:
        raise ValueError("Timestamp too old")

    # Build signed content
    signed_content = f"{webhook_id}.{webhook_timestamp}.{payload.decode()}"

    # Decode secret (strip "whsec_" prefix, base64-decode)
    secret_bytes = base64.b64decode(secret.split("_")[1])

    # Compute HMAC-SHA256
    computed = base64.b64encode(
        hmac.new(
            secret_bytes,
            signed_content.encode(),
            hashlib.sha256,
        ).digest()
    ).decode()

    # Compare against each signature in the header
    signatures = [
        sig.split(",")[1]
        for sig in webhook_signature.split(" ")
    ]

    if computed not in signatures:
        raise ValueError("Invalid signature")

    return json.loads(payload)

# Flask example
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/allo", methods=["POST"])
def handle_webhook():
    try:
        event = verify_webhook(
            request.get_data(),
            request.headers,
            os.environ["WEBHOOK_SECRET"],
        )
        print(f"Verified event: {event['topic']}")
        return "", 200
    except ValueError as e:
        print(f"Verification failed: {e}")
        return "", 400

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "math"
    "net/http"
    "strconv"
    "strings"
    "time"
)

func verifyWebhook(payload []byte, headers http.Header, secret string) error {
    webhookID := headers.Get("webhook-id")
    webhookTimestamp := headers.Get("webhook-timestamp")
    webhookSignature := headers.Get("webhook-signature")

    // Validate timestamp (5-minute tolerance)
    ts, _ := strconv.ParseInt(webhookTimestamp, 10, 64)
    if math.Abs(float64(time.Now().Unix()-ts)) > 300 {
        return fmt.Errorf("timestamp too old")
    }

    // Build signed content
    signedContent := fmt.Sprintf("%s.%s.%s", webhookID, webhookTimestamp, string(payload))

    // Decode secret (strip "whsec_" prefix, base64-decode)
    parts := strings.SplitN(secret, "_", 2)
    secretBytes, _ := base64.StdEncoding.DecodeString(parts[1])

    // Compute HMAC-SHA256
    mac := hmac.New(sha256.New, secretBytes)
    mac.Write([]byte(signedContent))
    computed := base64.StdEncoding.EncodeToString(mac.Sum(nil))

    // Compare against each signature in the header
    for _, sig := range strings.Split(webhookSignature, " ") {
        parts := strings.SplitN(sig, ",", 2)
        if len(parts) == 2 && parts[1] == computed {
            return nil
        }
    }

    return fmt.Errorf("invalid signature")
}

Verifiez toujours les signatures en production. Ignorer la verification expose votre application a des evenements webhook usurpes.

API

Webhooks

Conversations

Personnes

Entreprises

Deals

Notes

Fils de discussion

Numéros de téléphone

Tags

Modèles de résumé

Utilisateurs

SMS

Analytiques

Power Dialer

Partner

En-tetes de signature

Secret de signature

Algorithme de verification

Exemples de code

​En-tetes de signature

​Secret de signature

​Algorithme de verification

​Exemples de code

En-tetes de signature

Secret de signature

Algorithme de verification

Exemples de code