Webhooks

Authway uses webhooks to automatically notify your application any time certain changes happens in Authway.

Webhooks can be set up per event stream, where a stream is responding to a major information object for examples person, user or organisation. It is possible to set up multiple webhooks for a single stream and naturally it is possible to set up webhooks for different streams. The webhooks are grouped in a webhook system. The webhook system will typically be one for the consuming application. If one webhook is failing for a system, all webhooks for that system is stopped, which can affect how you choose to group your webhooks.

By default you will only be able to receive events that is owned by the same tenant as the Webhook is registered for.

Handling events

Choose event to recieve

When configuring a webhook, you can use the API to choose which events will send you payloads. This is done by setting a topic to the stream or a specific event. Only subscribing to the specific events you plan on handling limits the number of HTTP requests to your application. You can also subscribe to all current and future events. By default, webhooks are only subscribed to the future events. You can change the topic at any time, but for an existing webhook, it will only affect future events.

Advanced Topics

A topic is flexible and you can combine more than one “thing” in a topic by separating each identifier with “,”. For example:

Respond immediately to events

When receiving an event to your webhook, it is strongly recommended to respond with a 200 Ok (or another 2XX status code) as quickly as possible. Failing to do so might trigger re-tries which can increase the load of your application more than necessary.

A common pattern to handle webhook events effectivly is to add the event body on a message queue and immediately respond with a success status code. The internal queue can then be processed by a background worker.

Re-tries of failed events

For a configured webhook we guarantee that subscribed events are delivered at least once and in correct order (per webhook). If we get a timeout, a network failure or if we receive a response with status code 408 or any 5XX we’ll retry to send the payload again. Authway uses an exponential backoff scheme when doing re-tries and if all re-tries fails the webhook system will stopped. When this happens we will notify you by the registered e-mail address. It is your responsibility to re-start a stopped webhook system when your application is ready to handle the events again.

If Authway is causing the failure, we will also re-start the webhook system after we have corrected the issue.

Ignoring duplicate events

It is possible to receive the same event more than once, so we recommends that you handle webhook events using idempotent operations. One way of doing this is logging the EventId of the events that you have processed and ignoring subsequent requests with the same EventId.

Order of events

Authway guarantees that events within a webhook is delivered in the same sequence that they are happening. Between webhooks there are no guarantees of ordering, so your logic should handle cases where events are delivered out of order. If you create separate webhook systems, the ordering of the events between these systems is also not guaranteed.

Securing webhooks

Validating events are from Authway

Since the webhook receiver is available on the public Internet it is very important that you validate the incoming request before processing it. We recommend that you start by checking that all three custom HTTP headers are available. From security perspective the X-IRM-Signature header is the important one. Use your secret (that you used during registration) to calculate a HMAC-SHA256 signature of the received body.

C#:

using System;
using System.Security.Cryptography;
using System.Text;

class WebhookSignature
{
   public static string ComputeSignature(string data, string secret)
   {
       HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
       byte[] stringBytes = Encoding.UTF8.GetBytes(data);
       byte[] hashedValue = hmac.ComputeHash(stringBytes);
       return Convert.ToBase64String(hashedValue);
   }

   public static void Main (string[] args)
   {
       Console.WriteLine(ComputeSignature("messageBody", "apikey"));
   }
} 

PHP:

function compute_signature($data, $secret) {
    return base64_encode(hash_hmac('sha256', $data, $secret, true));
}

echo(compute_signature('messageBody','apikey')); 

Require authentication

Authway supports Basic authentication when calling your webhook. You provide the username and password when registering the webhook.

Obfuscating webhook URL

A minor improvment in the security of webhooks is to make the endpoints harder to guess. This can be done by adding a series of random numbers and letters to your endpoint URL. For example https://api.yourapplication.com/webhooks/j490smlkfs034jld94jlae045 is harder to guess than https://api.yourapplication.com/webhooks.

Testing Webhooks

It is not necessary for you to immediately create och deploy a service that can receive webhook payloads. Instead we recommend you to start with ay of the service on Internet that allows you to receive HTTP POST calls, for example https://webhook.site/. That service makes it really easy to get something up and running, and you can easily see the webhook payload directly in your browser.

To start receiving webhooks you must first start (activate) the webhook system by calling api/systems/{systemId}/start. Trigger some events in the source system and you should soon see POST arriving in the browser.

You can also stop the pushing of new events by calling api/systems/{systemId}/stop. If you want to simulate that the system have been stopped because of a failure you can use the same API. Use the source system to create some more events and then start the system again, and you should see all events be posted until it catches up to the last existing event.

You can also get information about the last date/time and event id that have been successfully posted to your webhook by making a get request to api/systems/{systemId}.

Exposing your Local Machine to the Internet

Since all webhooks are pushed over Internet, you’ll have to expose your local machine somehow, if you want to receive webhooks during development. We recommend that you use for example Ultrahook or ngrok to do that.

After configuring a service you’ll have to reconfigure your webhook system to receive payloads on your new URL.