Webhook Registration and Management

To receive PNSL resource events such as client.created or receivable.disbursed, register an HTTPS endpoint for webhook delivery.

1. Endpoint Requirements

Your server (Webhook Receiver) must meet the following requirements:

• Protocol: Use of HTTPS is mandatory to ensure the security of transmitted data.
• Availability: The URL must be publicly accessible to Axiym servers.
• Response: Upon receiving a POST request, your server must return an HTTP status of 2XX to indicate successful receipt.

2. Creating a Subscription

To register a URL, use the POST /webhooks/subscriptions method.

Request Parameters:

• endpoint (string, required): The full HTTPS URL of your service (e.g., https://api.example.com/webhooks).

Example Request:

{
  "endpoint": "https://api.example.com/webhooks"
}

The system will respond with a Subscription object containing a unique subscriptionId.

3. Testing and Verification

Once registered, you can verify that your infrastructure is ready to receive data without waiting for real events:

• Test Event: Call POST /webhooks/subscriptions/{subscriptionId}/tests to send a simulated notification to your address.
• List Subscriptions: You can view all active URLs via GET /webhooks/subscriptions.
• Deletion: If notifications are no longer needed, use DELETE /webhooks/subscriptions/{subscriptionId}.

4. Security and Signature Verification

For deliveries that include signature metadata, use the following headers to verify the notification:

• X-Signature: The digital signature of the request body.
• X-Key-Id: The identifier of the public key required to verify the signature.
• X-Algorithm: The algorithm declared for the delivery.

Verification Process:

1. Obtain the key identifier from the X-Key-Id header.
2. Request the public key via the API: GET /webhooks/public-keys/{publicKeyId}.
3. Use the retrieved publicKey and algorithm to verify the signature.

Important: Follow the signature-verification guide before trusting a delivery.