> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recevez des notifications en temps reel pour les paiements, violations de politiques et evenements d'agents.

## 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

```typescript theme={null}
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

```bash theme={null}
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 :

```json theme={null}
{
  "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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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");
  });
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## Tester les webhooks

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

```bash theme={null}
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 :

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
  -H "X-API-Key: awx_your_api_key"
```

## Gestion des webhooks

```bash theme={null}
# 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

<Tip>
  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.
</Tip>

* **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.