UNS Webhooks

Suggest Edits

Introduction

Enables developers to receive real time updates around name events.
UNS uses web-hooks to notify your service or application when an event happens to a name. Web-hooks are usefully for asynchronous events like when, a name expires, when a user looses ownership of a given name as it has been revoked, or other actions like when a name gets its profile picture updated or its Universal Ledger badge gets updated.

A web-hook enables UNS to push real-time notifications to your app. UNS uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Web-hook events currently enabled

The following events are enabled to subscribe and get real time notifications when a name triggers any of the events below.

  • NAME_REVOKED

Validate the web-hook events

UNS signs all web-hooks events it sends to your endpoints by including a signature in each event's X-Uns-Signature header. This allows you to verify that the events were sent by UNS, not by a third party.

Before you can verify signatures, you need to retrieve your endpoint’s secret, it can be found in your Web-hook resource when fetching the specific web-hook resource. UNS generates a unique secret key for each endpoint.

Verify web-hook signatures

The X-Uns-Signature header included in each signed event contains a timestamp (t) and a signature (s).

X-Uns-Signature:  
t=1492774577,  
s=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

UNS generates signatures using a hash-based message authentication code (HMAC) with SHA3-256.

  1. Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and s corresponds to the signature. You can discard all other elements.

  1. Prepare the signed_payload string

The signed_payload string is created by concatenating:

The timestamp (as a string)
The character .
The actual JSON payload (that is, the request body)

  1. Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

  1. Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance. (We suggest a tolerance of 300 seconds)

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Considerations when using UNS web-hooks

  • UNS expects a response code between 200 and 299, we suggest use 204 (No content)
  • Developer have 3 seconds to reply the request from UNS, otherwise UNS will flag the event as failed delivery.
  • At 5 failed notification, UNS will disabled the specific web-hook resource.

Updated 10 months ago