Skip to main content

Authorization & Webhooks - Overview

Introduction​

The Authorization Service enables secure programmatic access to the Global Banking API suite through temporary JWT (JSON Web Token) bearer credentials, while the Webhooks engine streams asynchronous, event-driven status notifications directly to your server infrastructure.

Key Features​

  • Company Login & Credential Exchange: Exchange your clientId and apiKey for a signed Bearer token valid for 60 minutes.
  • Stateless Authentication: Pass Bearer tokens in standard Authorization: Bearer <token> headers across all protected endpoints.
  • Real-Time Event Webhooks: Receive immediate HTTP POST callbacks when critical resources change state:
    • Payment Status: Track payment lifecycles from Requested to Completed or Failed.
    • FX Orders: Monitor foreign exchange trade fills and settlements.
    • Beneficiaries: React instantly when beneficiary screening or compliance review changes.
  • Event Idempotency & Signatures: Verify webhook authenticity and event timestamps to guard against replay attacks and guarantee delivery integrity.

Authentication Workflow​

sequenceDiagram
    autonumber
    participant App as Client Application
    participant Auth as Authorization Service (/users/login)
    participant API as Protected Banking APIs
    participant Hook as Client Webhook Listener

    App->>Auth: POST /users/login (clientId, apiKey, mode="apiKey")
    Auth-->>App: 200 OK (token, companyId, valid 60m)
    App->>API: GET/POST /... (Authorization: Bearer <token>)
    API-->>App: API Response
    Note over API,Hook: Asynchronous State Changes (Payments, FX, Beneficiaries)
    API->>Hook: POST /webhook (PAYMENT_STATUS_CHANGE)
    Hook-->>API: 200 OK (Acknowledged)

Token Expiration & Refresh​

Tokens generated by the /users/login endpoint are valid for 60 minutes (3600 seconds). We recommend caching the access token in memory or a centralized secret store and refreshing it prior to expiration to maintain uninterrupted API throughput.

Base URLs​

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

Webhook Security & Best Practices​

  1. Verify Signatures: Ensure all incoming requests originate from the Ahrvo gateway by validating signature headers and secret keys.
  2. Respond with 200 OK: Return an HTTP 200 status code promptly within 5 seconds of receiving an event. Perform extensive background processing asynchronously.
  3. Idempotent Handling: Implement deduplication using the resource identifier and timestamp fields in the event payload.

Support​

For authorization assistance, API credentials, or webhook debugging, contact support@ahrvo.com.