API Reference

Introduction

Webhooks are user-defined HTTP callbacks that are triggered by specific events in our system. They allow for real-time data exchange and process automation based on the events within our platform. This document outlines how to work with our webhooks, including the actions you can register for, and the method to verify the authenticity of webhook requests from our system.

Actions

You can register your webhooks to listen for the following actions. This list can be increased in the future.

  • scCreated: Triggered when a new subscription contract is created.
  • scUpdated: Triggered when a subscription contract is updated.
  • baSuccess: Triggered when a billing attempt is successful.
  • baFailure: Triggered when a billing attempt fails.
  • cpmUpdated: Triggered when a customer payment method is updated or replaced

Verify webhooks

To ensure the security of data transmission and to verify that incoming webhook requests are indeed from our system, we use the X-Awtomic-Signature header in all of our requests. This header contains a hexadecimal digest, which is generated by hashing the webhook's payload with a secret key using SHA256. Your secret key can be retrieved in the GET /webhooks endpoint.

Verification steps

1. Retrieve Your webhooksSecret

The webhooksSecret is a unique key provided to you, which can be retrieved via the "Get Webhooks Listeners" endpoint in our API. This key is essential for validating the integrity and origin of the webhook payload.

2. Compute the Signature

When you receive a webhook, compute the HMAC SHA256 hash of the payload using your webhooksSecret. The payload must be converted to a JSON string before hashing.

For example in JS:

const crypto = require('crypto');

const signature = crypto.createHmac('sha256', webhooksSecret)
                  .update(JSON.stringify(requestBody))
                  .digest('hex');

3. Compare the Signatures

The signature you've computed in the previous step should match the X-Awtomic-Signature header value received in the webhook request. If they match, the request is verified as coming from our system.