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.

Once armed webhooks will not be marked as accepted if a successful response is not received when sending the webhook to the endpoint. The unaccepted webhooks will be fired again to the endpoint on the next re-attempt.

A disabled Endpoint will not be armed (check the IsArmed property on the Endpoint). To re-enable the endpoint review the errors on the endpoint and ensure these issues are resolved. You then follow the Registering an Endpoint process using the same Endpoint Url. This will reattempt the arming process.