Webhooks

Webhooks are used to keep track of the state of user data within Registration. Webhooks may be created to send notifications whenever an attribute or plural is created, changed, or deleted. Once configured, Janrain delivers changes in state to a pre-determined URL as a JSON object. If an error occurs, Janrain will try to send the message three times to avoid temporary networking glitches.

Note that webhooks only support port 80 (for HTTP endpoints) and port 443 (for HTTPS endpoints).

Required Configuration Information

The following information is needed to configure a webhook:

  • Capture Application ID
  • Entity Type – What capture entity type should each webhook respond to (typically user).
  • Callback URL (or URLs) – What URL to POST to for each webhook.
    • Supported protocols:
      • HTTP
      • HTTPS (TLS 1.0 and above)
  • Event Types – What sort of events should each webhook respond to:
    • ADD – When a user record is created.
    • UPDATE – When profile information from a user record is updated.
      • For the UPDATE event type, you must provide a list of user record profile attribute changes each webhook should respond to. A list of attributes to choose from can be found in the Janrain Console in the Manage Schema section.
    • DELETE – When a user record is deleted.
  • Callback Hash (optional) – A unique identifier for each webhook. If a callback hash is not provided, Janrain will generate one for you.

Implementation Steps

  1. Request a webhook through the Janrain Support Portal.
  2. Provide required configuration information (listed above).
  3. Janrain will contact you when the webhook is deployed and ready to use.

Retry System

The retry system handles network problems and other transient issues. In the event that a webhook call fails, the system will retry the call up to three times; retries occur if a webhook fails to respond within 10 seconds. This 10-second retry interval is not configurable.

When a failure happens, the event is logged with Janrain.

Response

Responses are returned in the body of POST requests as JSON objects inside an array. Each response consists of:

  • Key-value pairs for the uuid from the user record
  • The entity_type used
  • A timestamp recording when the event took place
  • The callback hash
  • The client_id from where the webhook was triggered

To verify that a webhook response originated with Janrain, compare the callback hash value in the response with the callback hash established when the webhook was configured.

When an action triggers the webhook, Janrain sends a list of JSON objects to the callback URL defined in the configuration. You will need to implement code to process the information delivered to this location.

The following is an example POST response from a webhook:


[
  {
    "uuid":"12345678-4321-1234-4321-123456789123",
    "entity_type":"user",
    "datetime":"2012-04-07T22:26:10.947Z",
    "hash": "1234567891234567891234567891234567891234",
    "client_id":"98765432198765432198765432198765"
  }
]