Webhooks #

Webhooks can be used to generate external notifications of user and/or customer changes. These notifications, when combined with the REST API are essential for automating user provisioning and keep external configuration/billing systems up to date.

The web hook events will trigger for C.R.U.D events on users and customer. The REST API can then be used by the receiving application to query the specific information about the changes using the Ids provided in the webhook payload.

Parameters #

Parameter	Options	Description
Entity type	User, Customer	The entity the trigger can fire for. Create multiple triggers to capture both User and Customer changes.
Event	Created / Updated / Deleted	Select one or more event types on which the trigger will fire. *Note: The event type which causes a trigger is in included in the payload.
URL	https://	Provide an HTTPS URL that the trigger will call when fired.
Request method	GET, POST, PUT	Choose the required request method for the webhook.
Request format	JSON, Form Data	Choose the required request format for the webhook if POST or PUT are selected as the Request method.
Additional payload data	Key/value pair	If required, additional static information can be added to the webhook payload. Enter any additional data as key/value pairs as required.
Retry attempts	0 - 10	Default 1. Enter the number of times that the webhook should retry if the at any point there is an unsuccessful

warning
Webhook trigger configuration is cached to improve performance. Any new triggers or changes to existing triggers may take up to 10 minutes before they take effect.

info
The timeout for a webhook request is 10 seconds. The time between retry attempts is equal to the Attempt Number x 2 Seconds

Payload Data #

The table below shows the data provided in the trigger payload.

Parameter	Description
triggerID	The unique id for the trigger the web hook request is being fired for.
id	The id of the entity which is changing (user Id or tenant Id).
tenantId	The customer tenant Id that the event is associated to.
eventType	The event type which generate the web hook. Either create, update or delete
customData	If configured against the trigger, any additional payload key/value pair information will be passed here.

tip
The triggerId can be found by editing a configured trigger in the Reseller Portal and copying the GUID from the end of the URL. e.g. https://reseller.myreports.com/en-GB/webhooks/00000000-0000-0000-0000-000000000000

Example JSON payload: #

Example JSON payload format for PUT/POST requests:

{
    "triggerId": "00000000-0000-0000-0000-000000000000",
    "id": "1468547c-a945-41d4-95e3-ffffffffffff",
    "tenantId": "a0ea7445-df78-4487-ffffffffffff",
    "configurationType": "user",
    "eventType": "update",
    "customData": {
        "myitemkey1": "myitemval1",
        "myitemkey2": "myitemval2"
    }
}

Example FORM Data payload #

Example Form Data payload for PUT/POST requests:

[triggerId, 00000000-0000-0000-0000-000000000000], [tenantId, a0ea7445-df78-4487-ffffffffffff], [id, 1468547c-a945-41d4-95e3-ffffffffffff], [configurationType, user], [eventType, update],[myitemkey1, myitemval1], [myitemkey2, myitemval2]

Example GET request #

If the Request method of GET is configured for the Webhook, the payload data is passed as query string parameters in the request.

http://example.url.com?triggerId=00000000-0000-0000-0000-000000000000&tenantId=a0ea7445-df78-4487-ffffffffffff&id=1468547c-a945-41d4-95e3-ffffffffffff&configurationType=user&eventType=update&hook=get&myitemkey1=myitemval1&myitemkey2=myitemval2