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.
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");
});
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.
