Setup

It is possible to get your notifications via webhook. To do this, add or update your notifications rules for an event you wish to receive webhook notifications for. You can do this by navigating to the notification rules in the user portal. Here you can add a webhook URL to a notification rule for an event. We accept URLs in the following format:

http[s]://example.com[:PORT][/example-path].

Where anything in square brackets is optional. HTTP (no ssl) is only allowed on our OTE environment.

Security

HMAC

To protect your server from unauthorized webhooks, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures.

By verifying the signature included in a webhook event, you confirm that the event was sent by Realtime Register, and has not been modified during transmission. You can generate a HMAC key by navigating to your account details.

The binary representation (UTF-8) of the raw body of each webhook notification will be hashed using the shared key and the SHA-256 digest algorithm. The hashed value will be Base64-encoded and included as the 'Signature' header. You can verify this signature by following the same steps for calculating the signature and comparing the two signatures. If the signatures match, you will know that the notification was sent by Realtime Register and has not been modified.

Example:

If my key is EXAMPLE_KEY and my raw JSON content is

{"payload": "examplePayload"}

then the corresponding hashed value will be:

99928fae027cc60240594ecf829369365ca1c9b9ec87106d04c319a45ee0bd49

Base64-encoded:

IDk5OTI4ZmFlMDI3Y2M2MDI0MDU5NGVjZjgyOTM2OTM2NWNhMWM5YjllYzg3MTA2ZDA0YzMxOWE0NWVlMGJkNDk=

Basic

As an alternative (or supplementary) authentication, basic authentication is also supported. In your account details, you can set a username and password for basic webhook authentication. This username and password as 'username:password' will then be Base64-encoded and included in the 'Authorization' header. Please note that this only guarantees that the webhook event was sent by Realtime Register, not that it wasn't modified during transmission.

Example:

For exampleUser:examplePassword

The Base64-encoded value will be:

ZXhhbXBsZVVzZXI6ZXhhbXBsZVBhc3N3b3Jk

And the header value 'Authorization' will be:

Basic ZXhhbXBsZVVzZXI6ZXhhbXBsZVBhc3N3b3Jk

Content

When an event is triggered, the notification is added to a queue, and will be sent to the URL corresponding to the type of event or its parent event. The content is identical to the

response format of the get request.

Successful delivery

An HTTP-response with status code 200, 201 or 202 will be seen as a successful delivery and the corresponding notification will be removed from the queue.

Failure Handling

If a webhook fails to deliver to your server, we will retry a total of 5 times to deliver the notification with the following time intervals:

• 10 seconds
• 30 seconds
• 2 minutes
• 5 minutes
• 15 minutes

If we are still unable to deliver the webhook to your server, an email will be sent to your e-mail address notifying you of the delivery problem, this e-mail will contain an optional message describing an error and an optional HTTP-status code we received from your server.

As the event queue is global per user, any failure in sending to a webhook URL for specific event will also mean that all other notification events will fail to deliver until the issue is resolved.

If the issue has been resolved, it will take maximum of 15 minutes before the queue will trigger another webhook.