Webhooks

Presentation

Les webhooks delivrent des notifications d’evenements en temps reel a votre application via des requetes HTTP POST. Utilisez-les pour reagir aux paiements, violations de politiques, changements de statut des agents et evenements de session x402.

Configuration des webhooks

Via le SDK

const webhook = await aw.webhooks.create({
  url: "https://your-app.com/webhooks/agentwallex",
  events: [
    "payment.completed",
    "payment.failed",
    "agent.frozen",
    "policy.violated",
  ],
  secret: "whsec_your_signing_secret",
});

Via l’API

curl -X POST https://api.agentwallex.com/api/v1/webhooks \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/agentwallex",
    "events": ["payment.completed", "payment.failed", "agent.frozen", "policy.violated"],
    "secret": "whsec_your_signing_secret"
  }'

Types d’evenements

Evenement	Description
`payment.completed`	Transaction confirmee on-chain
`payment.failed`	Transaction echouee ou annulee
`payment.pending`	Transaction soumise, en attente de confirmation
`agent.frozen`	Le portefeuille de l’agent a ete gele
`agent.unfrozen`	Le portefeuille de l’agent a ete degele
`policy.violated`	Transaction rejetee par le moteur de politiques
`x402.session.expired`	Budget ou TTL de la session x402 depasse
`approval.requested`	Transaction de haute valeur en attente d’approbation humaine

Charge utile du webhook

Chaque livraison de webhook inclut une charge utile JSON avec cette structure :

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2025-06-15T14:30:00Z",
  "data": {
    "transaction_id": "tx_xyz789",
    "agent_id": "agent_abc123",
    "amount": "50.00",
    "token": "USDC",
    "chain": "eip155:8453",
    "hash": "0xabc...def",
    "status": "confirmed"
  }
}

Verification de signature

Chaque livraison de webhook inclut un en-tete de signature pour la verification. Verifiez toujours les signatures avant de traiter les evenements webhook.

Comment ca fonctionne

AgentWallex signe chaque charge utile de webhook en utilisant le secret que vous avez fourni lors de l’enregistrement. La signature est envoyee dans l’en-tete X-AgentWallex-Signature.

Exemple de verification

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post("/webhooks/agentwallex", (req, res) => {
  const signature = req.headers["x-agentwallex-signature"] as string;
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    "whsec_your_signing_secret"
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // Process the event
  const event = req.body;
  console.log(`Received ${event.type} event`);
  res.status(200).send("OK");
});

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Utilisez toujours une comparaison en temps constant (par ex., timingSafeEqual ou hmac.compare_digest) lors de la verification des signatures pour prevenir les attaques par analyse temporelle.

Tester les webhooks

Envoyez un evenement de test a votre point de terminaison webhook :

curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
  -H "X-API-Key: awx_your_api_key"

Consulter les livraisons

Verifiez l’historique de livraison d’un webhook :

curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
  -H "X-API-Key: awx_your_api_key"

Gestion des webhooks

# List all webhooks
GET /webhooks

# Get a specific webhook
GET /webhooks/:id

# Update a webhook
PUT /webhooks/:id

# Delete a webhook
DELETE /webhooks/:id

Bonnes pratiques

Repondez aux livraisons de webhooks avec un code de statut 2xx dans les 5 secondes. Si votre gestionnaire doit effectuer un traitement lourd, accusez reception du webhook immediatement et traitez de maniere asynchrone.

Verifiez toujours les signatures avant de traiter les evenements.
Gerez les doublons — Les livraisons de webhooks peuvent etre retentees. Utilisez le champ id pour l’idempotence.
Renvoyez 200 rapidement — Accusez reception avant d’effectuer un traitement lourd.
Surveillez les echecs de livraison — Verifiez le point de terminaison des livraisons pour les livraisons echouees.
Utilisez des filtres d’evenements specifiques — Abonnez-vous uniquement aux evenements dont vous avez besoin plutot que de recevoir tous les evenements.

Démarrage

Plateforme

Fonctionnalités

Guides

Presentation

Configuration des webhooks

Via le SDK

Via l’API

Types d’evenements

Charge utile du webhook

Verification de signature

Comment ca fonctionne

Exemple de verification

Tester les webhooks

Consulter les livraisons

Gestion des webhooks

Bonnes pratiques

​Presentation

​Configuration des webhooks

​Via le SDK

​Via l’API

​Types d’evenements

​Charge utile du webhook

​Verification de signature

​Comment ca fonctionne

​Exemple de verification

​Tester les webhooks

​Consulter les livraisons

​Gestion des webhooks

​Bonnes pratiques

Presentation

Configuration des webhooks

Via le SDK

Via l’API

Types d’evenements

Charge utile du webhook

Verification de signature

Comment ca fonctionne

Exemple de verification

Tester les webhooks

Consulter les livraisons

Gestion des webhooks

Bonnes pratiques