Callbacks

Overview #

Callbacks are created by a webhook consumer when they are subscribing to a webhook. Callbacks are the endpoints where the consumer wants to have the webhook events sent to. They consist of:

• Callback Name – a nice short name you want to give to your callback
• Callback URL – the endpoint where the consumer wants the events to be sent.
• Method – normally only POST is used but we’ve given you the option for PUT or PATCH.
• Security
  • None – Not recommended but more for a quick test.
  • HMAC – A signature sent in the Authorization header that uses symmetric encryption using a secret the consumer provides. See more details about HMAC security below.
  • OAuth 2.0 – Use client credentials to request an access token.
  • Enterprise has further options to secure callbacks including Mutual TLS.

Editing a callback #

Callbacks can be managed by any user within the same Consumer Group and Entity as the user who created the callback.

To edit a callback follow these steps:

1. Edit a subscription that uses the callback.
2. On the subscription page, there is a 3 dot menu in the callback area. In the 3 dot menu is an edit option.

Note: When editing a callback it impacts all other subscriptions that use the callback.

HMAC Security #

HMAC (Hash-based Message Authentication Code) is a symmetric encryption technique that uses a shared secret. When a consumer selects to secure the callback with a HMAC signature they must specify the following:

• Key Id: an identifier for the secret. This can be used by the consumer to know which secret should be used to validate the signature.
• Secret: the shared secret that they will use to validate the HMAC signature.

Once configured webhookie will apply the HMAC signature to all events sent to this callback.

The signature will appear in the Authorization header and takes the form of:

Authorization: Signature keyId=my-key-id,algorithm=HmacSHA256,headers=(request-target) date x-trace-id x-span-id,signature=<signature>

where:

• keyId = the key id specified in the callback.
• algorithm = HmacSHA256 – indicating a SHA256 signature is applied using the HMAC technique.
• headers = the headers of the HTTP request that are used as input into the signature. These include:
  • (request-target) – which is not a header but the HTTP method appended with the endpoint. E.g. POST https://example.org
  • date – which is a UTC timestamp – 2021-09-02T12:27:52.640269Z
  • x-trace-id – the trace id – a unique id for the event
  • x-span-id – the span id – a unique id for the event sent to this subscription.
• <signature> = the SHA256 signature – which is calculated as follows – sha256(“(request-target): POST https://example.com/callback date: 2021-09-02T12:27:52.640269Z x-trace-id: 1 x-span-id: 1″, $secret)

The signature can then be validated in the callback by decoding the signature using the shared secret. The callback can then confirm that the unencrypted signature matches the HTTP headers to ensure the integrity of the event and in addition, the timestamp can be verified to avoid replay attacks.

OAuth 2.0 #

OAuth 2.0 using the client credentials flow can also be used to secure the callback. When securing via OAuth 2.0 the consumer must provide:

Token Endpoint: The OAuth 2.0 authorization servers API endpoint to retrieve the access token.

Client Id: The client ID used for the subscription. Note it is recommended to use one client Id per subscription.

Client Secret: The clients secret.

Scopes: Optional. If used will limit the access to the scopes requested.

When an activated subscription has OAuth 2.0 configured, webhookie will make a call to the token endpoint to retrieve an access token. If successful webhookie will place the access token in the Authorization header in the form:

Authorization: Bearer <accesstoken>

Once an access token has been retrieved it will be cached and reused for the subscription until it expires.

If unsuccessful to retrieve an access token then the subscription will become blocked.