Webhooks

Webhooks (https://en.wikipedia.org/wiki/Webhook) are a way for P6 Auth to notify registered listeners of events that occur within the Authentication and Authorization server.

Event notification is regarded as a much more efficient way to synchronize behaviour with the centralised Authentication and Authorization infrastructure; compared to polling P6 Auth for changes for example!

Security¶

Verifying that a notification event delivered by a webhook Http POST is from your P6 Auth defined Webhook service is essential and is often cited as a security concern with Webhook notifications in general.

P6 Auth Webhooks provide two mechanisms to assist with this:

Shared Secret
Signatures

Shared Secret¶

This is the simplest form of identification and requires the use of a pre-agreed shared secret (word or phrase) that is added to each generated notification and should be validated by the receiving party.

Payload Signatures¶

Notification payload signatures are generated and added to each generated notification. Two signature types are supported:

HMAC (Requires an agreed secret to generate)
RS256 (RSA 256 PKI requiring key exchange)

Minimal Content in Notification Payload¶

Notifications do not contain verbose or rich data payloads relating to the type of event that triggered. It is a more secure policy to only provide essential key type information in payloads that require the receiving party to have permission to access additional APIs/DSL/Endpoints to further qualify the event originator.

Format of the Http POST¶

Headers¶

Name	Description
X-P6auth-UUID	A unique value for this notification event
X-P6auth-Hook-UUID	The Id of the Webhook that generated this event
X-P6auth-Event	The type of event (see available selection in UI)
X-P6auth-Event-Sequence	The sequence number (1..n) of this event when queued awaiting delivery
X-P6auth-Secret	The Webhook shared secret (if defined)
X-P6auth-Signature	The signature of the JSON payload (if defined)
X-P6auth-Attempt-Number	Ideally `1` but depends on the reliability of the receiver
Content-type	Fixed value: `application/json`

JSON Body (Payload)¶

The current webhook events supported by P6 Auth relate to database entity Add/Delete/Update operations. The following payload JSON is common to all entity_ type events.

Note

Additional payload formats may be supported in future

Attribute Name	Description
id	UUID for this notification event
timestamp	Creation timestamp (millis since epoch)
instance	The Id of the P6 instance associated with this event
type	`ADD`, `DELETE` or `UPDATE`
context	Event origination context
attributes	name/value pairs representing key value to use to retrieve context detail

Example:

{
  "id": "161d9874-8e05-4479-9fc8-76e9d2830dd8",
  "timeStamp": 1639149449158,
  "instance": "dev",
  "type": "UPDATE",
  "context": "user",
  "attributes": {
    "realm": "b2",
    "email": "simon.temple@amalto.com"
  }
}

Event Delivery Failure¶

P6 Auth Webhook notification event delivery is designed to handle unreliable and offline receivers.

This may be a server that is unavailable due to networking issues or a server that is down, for scheduled maintenance for example.

All notification events are persisted by the P6 Auth infrastructure and only removed when a TTL (time to live) and/or max delivery retries are exhausted.

Delivery control is configured using:

TTL Minutes (Persisted event time-to-live expressed in minutes)
Max Delivery Attempts (Maximum attempts made to deliver notification to receiver)
Pacing Millis (Fixed interval expressed in milliseconds that the delivery service will wait before retrying failed delivery)

Note

Webhooks without a defined delivery URL will only be removed after the TTL expires. This value should be configured long enough for a receiver to collect them using the ‘GET’ endpoint API

History¶

Delivery history is a feature that enables a user to record and store a trace of the last delivery attempt made by the delivery service

History is stored on a per-webhook basis and can be examined via the portal user interface.

This is a great way to diagnose Http connectivity problems

Warning

History should be disabled once a reliable Webhook event delivery configuration has been established

Event Origination Context¶

The P6 Auth infrastructure serves all P6 instances and associated devices/apps. The event origination context is used to ensure that only webhooks configured within a given context are triggered when events are generated by that context.

There are two types of context supported

Per Instance
Global

An example of a per instance event context would be an ENTITY_ADD_USER event that is generated as a user is added/associated with the dev instance of P6. Here the context would be dev and only Webhooks associated with the dev instance will receive this event.

Users added to the test instance would not generate events for Webhook definitions associated with the dev instance!

This is a simple per-instance isolation mechanism however not all P6 Auth entities are able to be identified as being related to an instance. For this case we use the Global context or * instance context.

Per Instance Webhook Events

ENTITY_USER_ADD,
ENTITY_USER_UPDATE,
ENTITY_USER_DELETE,
ENTITY_PERMISSIONSET_ADD,
ENTITY_PERMISSIONSET_UPDATE,
ENTITY_PERMISSIONSET_DELETE,
ENTITY_ORG_ADD,
ENTITY_ORG_UPDATE,
ENTITY_ORG_DELETE,
ENTITY_SSOCONNECTION_ADD,
ENTITY_SSOCONNECTION_UPDATE,
ENTITY_SSOCONNECTION_DELETE

Global Instance Events

ENTITY_REALM_ADD,
ENTITY_REALM_UPDATE,
ENTITY_REALM_DELETE,
ENTITY_CLIENT_ADD,
ENTITY_CLIENT_UPDATE,
ENTITY_CLIENT_DELETE,
ENTITY_INSTANCE_ADD,
ENTITY_INSTANCE_UPDATE,
ENTITY_INSTANCE_DELETE,

Portal Configuration User Interface¶

A user requires the following permissions to use the Webhooks configuration:

webhook=read (to list and review the Webhooks)
webhook=edit (to add and update Webhooks)
webhook=delete (to remove a Webhook)

The Webhooks’ user interface is the fifth tab of User Administration and allows webhook definition with an Event Origination Context of the currently select P6 Instance

It is here a user has access to the History if enabled.

Webhook Edit

Enable/Disable¶

Webhooks can be enabled/disabled. A disabled webhook will not generate notification events.

Note

Undelivered notification events that exist when a webhook becomes disabled will still be delivered (if possible)

Notification Delivery Properties¶

Webhook notification delivery behaviour can be customized using a number of properties:

Property Name	Description
post.pacing.millis	Optional. Milliseconds to wait before attempting the retry of a failed notification delivery (default: 0)
post.custom.headers	Optional. A comma separated list of Http headers that will be included in the notification deliver POST
post.max.attempts	Optional. The maximum number of attempts made to deliver a notification event (default: 2)
post.insecure	Optional. If `true` the TLS certificate validation of the receiver will be skipped (default: false)
post.signature.hmac.secret	Mandatory if signature type = HMAC. A shared word or passphrase
post.signature.rs256.pem	Mandatory if signature type = RS256. A private key in PEM format (must be wrapped with -----BEGIN PRIVATE KEY-----, -----END PRIVATE KEY----- )