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

# Webhooks

> Real-time event notifications

# Webhooks

Amrood sends real-time HTTP POST notifications to your platform's registered `webhook_url` when events occur.

## Setup

Register your webhook URL when creating a platform, or update it later:

```bash theme={null}
PATCH /v1/platforms/{platform_id}
{ "webhook_url": "https://your-server.com/webhooks/amrood" }
```

## Events

| Event                        | Description                         |
| ---------------------------- | ----------------------------------- |
| `agent.funded`               | Agent wallet received funds         |
| `agent.payment.received`     | Incoming payment from another agent |
| `agent.payment.sent`         | Outgoing payment confirmed          |
| `agent.settlement.completed` | T+2 settlement to owner's bank      |
| `agent.withdrawal.completed` | Manual withdrawal processed         |
| `owner.kyc.completed`        | KYC verified                        |
| `owner.kyc.failed`           | KYC rejected                        |

## Delivery Management

View delivery history and retry failed webhooks:

```bash theme={null}
# List deliveries
GET /v1/webhooks/deliveries

# Retry a failed delivery
POST /v1/webhooks/deliveries/{delivery_id}/retry

# Send a test webhook
POST /v1/webhooks/test
```

## Payload Format

```json theme={null}
{
  "event": "agent.payment.received",
  "data": {
    "agent_id": "agt_xxx",
    "payment_id": "pay_yyy",
    "from": "agt_zzz",
    "amount": 150,
    "reference": "translation_job_42"
  }
}
```

## Verification

Every webhook includes an `x-amrood-signature` header — an HMAC-SHA256 signature of the JSON body using your platform's webhook secret.

```python theme={null}
import hmac, hashlib, json

def verify(payload: dict, signature: str, secret: str) -> bool:
    body = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    expected = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

## Retry Policy

Failed deliveries (non-2xx response) are retried up to 3 times with exponential backoff (1s, 10s, 60s).