The Register system provides event notification via webhooks for customer systems to consume. This document will provide an overview of how this system works and is intended for a technical audience.

If you're unfamiliar with webhooks we recommend webhooks.fyi to understand the current best practices of the technology. We also recommend reading the spec from Standard Webhooks, while not yet a true standard, this is an effort to establish a common set of conventions that can be standardized in the future.

Topics Covered

• Basic terminology
• Setting up your first webhook
• Receiving Webhook Messages
• Verifying authenticity of webhook messages
• Managing existing webhooks

Basic terminology

The following terms will be used in this document with the provided definitions.

• Event Category
  • A logical group of events that can be subscribed to as a whole. Ex: The Brand Event Category includes all events that are related to a Brand Registration
• Event Type
  • A specific kind of event that has occurred.
  • Ex: The StatusChange event type is sent when a Registration moves into a new status.
• Webhook Message
  • Refers to the HTTP POST request that is sent to the customer's system. The relevant parts of the request are:
  • Headers
    • Webhook-Id
    • Webhook-Signature
    • Webhook-Timestamp
  • Body
    • The body of the request consists of the JSON payload of the webhook
• Webhook Destination
  • Refers to a combination of an Event Category and a URL that will receive the Webhook Messages

Setting up your first webhook

Creating Webhook Destinations is fully self service through the Register API. Interactive API documentation of the endpoints discussed throughout this document are available here.

In order to create your first webhook you will send a POST request to the /webhooks endpoint with a body indicating which Event Category you would like to receive and what URL should be used.