Arming an endpoint

You must arm your endpoint before you are able to receive webhook events

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.

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

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: '',
    ResourceUrl: '',
    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. 400 (Bad Request) is returned if the content received by Pay Advantage is null or empty.
  2. 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.
  3. 400 (Bad Request) is returned if the request is an empty array or not an array of webhook objects.
  4. 400 (Bad Request) is returned if the request array contains an item with null or empty values. All values for all items 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.