Arming an endpoint

The process of arming a webhook ensures that the data sent to your server from Pay Advantage is secure and has not been tampered. This is a security measure to ensure your endpoint is safe. The arming process validates the signature and payload is correct, once armed you will receive webhooks for all event types.

See our Javascript or Java github example for arming the process.

Example of the webhook payload (Verify the signature in the header x-payadvantage-signature):

POST yourapi.com/webhook HTTP/1.1
Host: yourapi.com
Content-Type: application/json; charset=utf-8
x-payadvantage-signature: YOUR_SIGNATURE
Content-Length: 323
Expect: 100-continue

  {
    Code: 'ABC123',
    MerchantCode: 'ABC123',
    DateCreated: '2023-12-01T04:49:36.760+00:00',
    DateUpdated: '2023-12-01T04:49:42.793+00:00',
    Event: 'webhook_endpoint.armed',
    ResourceCode: 'ABC123',
    EndpointCode: 'ABC123',
    EndpointUrl: 'https://yourapi.com/webhook',
    ResourceUrl: 'https://api.test.payadvantage.com.au/webhook_endpoints/ABC123',
    Status: 'sending'
  }

Within a minute (typically about 15 seconds) after registering an endpoint, Pay Advantage will run a series of test to ensure that the endpoint responds correctly to some random scenarios. For the endpoint to be armed it must return the following Http Status Codes for the scenarios described:

1. 403 (Forbidden) is returned if the Pay Advantage request does not include the header x-payadvantage-signature or the header value(s) are all null or empty.
2. 400 (Bad Request) is returned if the request is an empty array or not an array of webhook objects.
3. 400 (Bad Request) is returned if the request doesn't have the required fields in the webhook object. The mandatory fields are: Code, DateCreated, Event, Status, ResourceUrl
4. 400 (Bad Request) is returned if the request array contains a mandatory attribute with null or empty values. All values for all mandatory attributes should be populated.
5. 401 (Unauthorized) is returned if the x-payadvantage-signature does not match the signature your endpoint calculates based on the raw content received and the secret assigned to your endpoint.
6. 202 (Accepted) is returned if none of the above criteria eventuate. The endpoint should respond ASAP and not perform lengthy processing before returning a response. We recommend you queue these events and process them later using some strategy (new thread, message queues, etc).

During the arming process if the correct responses are not received for the tests within 30 seconds a timeout will occur and your endpoint could end up being disabled. You can view the status of this process from within the webhook register UI dashboard.

Once activated, webhooks will not be marked as accepted unless a successful response is received from the endpoint. The unaccepted webhooks will be reattempted again to the endpoint at a later time. The webhook will slow down sending the webhooks each time is receives an unsuccessful attempt until it will eventually disarm the webhook, and the arming process will need to be re-initiated.

A disabled Endpoint will not be armed. This is visable from the webhooks UI screen. To re-enable the endpoint review the errors on the endpoint and ensure these issues are resolved. You then follow the Registering an Endpoint by clicking the re-arm button or by using the same Endpoint Url.