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?
- 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:
- Extract the signature from the header
X-Ascend-Signature
. The value of the string is a comma separated string. Thev1
value represents the signature. - 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>
) - Sign the string by computing a
HMAC
with theSHA256
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');
-
Compare the signatures. You should compare the signature produced locally and the signature in the
X-Ascend-Signature
header. -
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.
- 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.
Updated 9 months ago