API Reference
Start typing to search…

Securing your webhooks


To ensure that your platform receives webhooks from Ascenda and not from a malicious third party, it's essential to adopt security measures. Ascenda recommends adopting at least one of the following suggested measures:

Webhook Signature

Ascenda's platform supports providing an HMAC-SHA256 signature to the webhook request. This signature value is generated using a shared secret key and the payload and provided in the request's header via a header value X-Signature.

On the receiving end, your webhook receiver should extract the X-Signature header and use the same shared secret key and payload to generate an HMAC-SHA256 signature. If the two signatures match, the payload is considered valid and has not been tampered with during transmission. If the signatures do not match, the payload has been modified or corrupted and should be discarded.

Signature Construction

  1. Sort JSON payload by key and convert to string
  2. HMAC-SHA256 the payload string
  3. Base64 strict encode the hash

Example implementation on client side:

def payload_signature(shared_secret, payload_hash)
  digest = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"),
                                shared_secret,
                                payload_hash.sort.to_h.to_json)
  Base64.strict_encode64(digest)
end

Examples 1:

shared_secret = "shared_secret"
payload_hash = {"timestamp":1643458800,"user_id":123,"event":"user_created"}
puts signature = payload_signature(shared_secret, payload_hash)

output: BCz+x0KbSyMcRSAFi60CgCI1VXmzLBReduS8Kvh3Ql4=

Examples 2:

shared_secret = "shared_secret"
payload_hash = {"order_id":"ABC123","total_amount":99.99,"status":"pending","timestamp":1643459100}
puts signature = payload_signature(shared_secret, payload_hash)

output: +hg52AaY0RWzeM9FSMKleaHyJj6MWDmo3OXgh7lGrfU=

Adding IPs to the Allowed List

Ascenda sends webhook requests to your webhook receiver endpoint from a set of fixed IP addresses. You can set up an IP whitelist on your webhook receiver endpoint to ensure that only Ascenda's platform can reach your endpoint.

Additional Authentication

To further secure your webhook receiver endpoint, there are two options you can configure:

  • HTTP Basic Authentication: requiring Ascenda's platform to provide a username and password with the webhook request to your endpoints.
  • API Key: Ascenda can send a header with the name of your choice with the preconfigured API key.

By adopting these security measures, you can ensure that your platform will receive the expected webhooks from Ascenda.