Skip to main content

Webhook Configuration and Notification Process (Client Side)

Webhooks serve as the communication bridge between Access Point Providers (APP) and Client (e.g. taxpayers’ ERP/accounting systems). When specific invoice events occur, the APP will trigger HTTP POST requests to the Client’s webhook URL. This ensures the Client’s system stays updated without having to call the APP. This is to be configured by Client to receive asynchronous notifications from APP.

Sample Webhook Payload: (see section 1.53 sample request)

Client webhook must return:

{
  "status": 200,
  "message": "ACKNOWLEDGED"
}

Webhook Setup:

  1. Implement a Webhook URL.
  • Client must expose HTTPS endpoint capable of handling POST requests with JSON payloads.
  • URL Path: client_base_url}/api/v1/invoice/webhook
  1. Secure the Endpoint.
a. Each notification includes these headers.
i. X-API-Key: Identifies the APP.
ii. X-Signature: HMAC-SHA256 of the payload + timestamp.
iii. X-Timestamp: ISO-20022 timestamp.
b. Client must validate these for each request.
  1. Register Webhook URL with APP.
  • Client provides their Webhook URL to the APP during onboarding/integration.
  • APP will dispatch a `Test Notification` to verify reachability.
  1. Ensure High Availability.
  • Client webhook must return 200 OK on success and response body key pair value of “message”: “ACKNOWLEDGED”.
  • Failures will result in retry attempts (exponential backoff).
  • After max retries, APP flags notification as FAILED.
  1. Ensure Best Practices.
  • Store processed event Ids in a persistent database.
  • Log all webhook attempts for auditing.
  • Implement monitoring (alerts on failed events).
  • Ensure webhook endpoint SLA (e.g. 99.999% uptime).
NB

In production, ensure that your webhook endpoint adheres to high availability standards to avoid communication lapses during transmission cycles.