Webhooks

Bêta

Les webhooks Pennylane sont en bêta. Pennylane recommande elle-même de conserver les endpoints changelog en solution de repli pendant que la fonctionnalité se stabilise. Types d'événements connus à ce jour : customer_invoice.e_invoicing_status_updated et dms_file.created.

S'abonner

<?php

use Pennylane\Sdk\Pennylane;

$client = new Pennylane(); // lit PENNYLANE_API_TOKEN

$subscription = $client->webhookSubscriptions->create(
    callbackUrl: 'https://example.com/webhooks/pennylane', // doit être en HTTPS
    events: ['customer_invoice.e_invoicing_status_updated'],
);
echo $subscription->secret;

Stockez le secret immédiatement

Le secret utilisé pour vérifier les livraisons n'est renvoyé qu'une seule fois, à la création. Stockez-le immédiatement dans votre gestionnaire de secrets ; vous ne pourrez plus le récupérer ensuite.

Gérez les abonnements avec list(), get($id), update($id, ...) et delete($id).

Recevoir et vérifier les livraisons

Pennylane signe les livraisons avec un HMAC du corps brut à l'aide de votre secret. Vérifiez avant de faire confiance :

<?php

use Pennylane\Sdk\Webhooks\Webhooks;
use Pennylane\Sdk\Exception\WebhookSignatureException;

$secret = getenv('PENNYLANE_WEBHOOK_SECRET'); // depuis votre gestionnaire de secrets

$raw = file_get_contents('php://input'); // le corps BRUT, ne pas le re-sérialiser
$signature = $_SERVER['HTTP_X_PENNYLANE_SIGNATURE'] ?? '';

try {
    $event = Webhooks::parseEvent($raw, signature: $signature, secret: $secret);
} catch (WebhookSignatureException $e) {
    http_response_code(400);
    exit('bad signature');
}

if ($event->event === 'customer_invoice.e_invoicing_status_updated') {
    // ...
}

http_response_code(200);
echo json_encode(['ok' => true]);

En-tête de signature

À la mi-2026, Pennylane ne documente pas encore précisément le nom ni l'encodage de l'en-tête de signature. Webhooks::verifySignature() est volontairement tolérante : elle accepte les encodages HMAC-SHA256 en hexadécimal comme en base64, avec ou sans préfixe sha256= ou hmac-sha256=, comparés en temps constant. Inspectez vos premières livraisons réelles pour confirmer l'en-tête (généralement X-Pennylane-Signature) et figez votre intégration en conséquence.

Vous pouvez aussi vérifier manuellement :

$isValid = Webhooks::verifySignature($rawBody, $signatureHeader, $secret);

Repli : changelogs

Pour une synchronisation à livraison garantie, interrogez les endpoints changelog. Ils renvoient des événements de changement par ressource, paginés par curseur, ce qui rend triviale une boucle de synchronisation incrémentale :

foreach ($client->changelogs->customerInvoices() as $event) {
    // chaque événement référence la facture modifiée
}

Des changelogs existent pour les factures clients, les factures fournisseurs, les clients, les fournisseurs, les produits, les lignes d'écriture, les transactions et les devis.