Skip to main content

​
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: 
PATCH /v1/platforms/{platform_id}
{ "webhook_url": "https://your-server.com/webhooks/amrood" }

​
Events (Phase 1)

EventDescription
agent.fundedAgent wallet received funds
agent.payment.receivedIncoming payment from another agent
agent.payment.sentOutgoing payment confirmed
agent.settlement.completedT+1 settlement to owner’s bank
owner.kyc.completedKYC verified
owner.kyc.failedKYC rejected

​
Payload Format

{
  "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. 
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).