Overview

Overview

Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, select the events you want to be notified about, and they will be sent to the URL provided.

To test Webhooks before setting up scripts, the Request Bin tool is an excellent utility that helps you see data come across as various events occur in the system.

When Should I Be Using Webhooks?

The case for webhooks is when you must act on specific events. At Stax Bill, this includes actions like customer creation, modifying a subscription, etc. If you would otherwise have to poll for data, you should be using webhooks.

How Should I Handle Webhook Requests?

There’s no official spec for webhooks, so how they are served and managed is up to the originating service. At Stax Bill, we have identified two key issues:

• Ensuring delivery/Detecting failure
• Protecting our system

To this end, we’ve implemented a 2-second timeout period and allow for three retries. We wait 2 seconds for a response to each request, and if there isn’t one or we get an error, we retry the connection. The retries will be sent at 1, 2, and 3 minutes after the original failure.

If you’re receiving a Stax Bill webhook, you must acknowledge receipt quickly. If no response is received, the system may continue to retry, which may cause issues if your system perceives this as new information or the Stax Bill triggers the timeout.

Ensure that your web server is returning a 2xx response to our servers. Any other response type will result in our server retrying a POST until we receive a 2xx response or the maximum time has expired. All events are retried at increasing intervals after the event occurs. Make sure you are not blocking our IPs that are trying to POST to your server.

Manage concurrency

When a user makes a number of changes in rapid succession, your app is likely to receive multiple notifications for the same user at roughly the same time. If you're not careful about managing concurrency, your app can process the same changes for the same user more than once.

For some applications, this is not a serious issue. Work that can be repeated without changing the outcome is called idempotent. If your app's actions are always idempotent, you don't need to worry much about concurrency.

Resilient Parsing

We do not guarantee the order of properties in our Webhook Payloads.

Note that new fields can be added anytime to our Webhook Payloads. The code used to parse webhooks should be resilient to these changes.

You will want to configure webhooks in Stax Bill Admin

Event Source

Stax Bill webhooks support a field to define where the source of the call originated from.

Current event sources:

• StaxbillUI
• API
• StaxbillReg
• StaxbillSSP
• Salesforce
• SubscriptionPlatform
• System
• {Custom Source}

When making calls via the API, you can enter a custom event source. To do this, add a header to the API call called x-audit-source you can then specify the source of the call.

📘

Example

x-audit-source:"test"

Or

private HttpClient GetHttpClient(string acceptType = "application/json", int timeout = 60)
        {
            var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Authorization = "Basic" + ApiKey;
            httpClient.DefaultRequestHeaders.Add("Accept", acceptType);
            httpClient.DefaultRequestHeaders.Add("x-audit-source", _auditSource);
        }