Webhooks

Ascend uses web hooks to notify organizations when an event happens. Ascend will send a POST request to a specified URL over HTTPS with a payload that includes the relevant information related to the event.

How to handle requests from Ascend?

1. Verify the request authenticity

Webhook requests include a custom header X-Ascend-Signature. The signature is a HMAC with SHA-256. In order to validate the request manually you should complete the following steps:

1. Extract the signature from the header X-Ascend-Signature. The value of the string is a comma separated string. The v1 value represents the signature.
2. Construct the string to be signed. The string should be constructed by concatenating the request timestamp and the body of the request separate by a colon (<timestamp>:<stringified request body>)
3. Sign the string by computing a HMAC with the SHA256 hash function. Use the secret key provided by Ascend.

const crypto = require('crypto');
const signedString = `${timestamp}:${requestBody}`
const hmac = crypto.createHmac('sha256', 'MY_SECRET')
    .update(signedString)
    .digest('hex');

4. Compare the signatures. You should compare the signature produced locally and the signature in the X-Ascend-Signature header.

5. Process the event

The request will include a payload that follows the schema:

{
    "type": "object",
    "properties": {
        "event_id": {
            "type": "string",
            "description": "A unique identifier for this event"
        },
        "event_name": {
            "type": "string",
            "description": "The name of the event"
        }
        "payload": {
            "type": "object",
            "description": "The event data"
        }
    }
}

The consuming endpoint should be able to handle different event types. By checking the event_name field a consumer should be able to differentiate between the different use cases.

3. Return a 200 response

You should send a successful 200 response to Ascend as soon as possible once you receive the event. Any other type of response will be considered a failure and the event will be retried. The event will also be retried when we considered that the request timed out.