Adding WebHooks

Webhooks allow us to push notifications to partners.

Tables - Adding Webhooks

Resource Template
/webhooks
Http Method POST
Description

Allows WUBS to add new webhooks for a partner.

URI is a required parameter and should be a valid formed URI starting with 'HTTPS'. 'isPrimary' is an optional parameter and can only have 'true' value.

Upon successful validation of parameters, a webhook will be assigned a unique ID (GUID like) which could be used later to update or delete a webhook.

Input
{
"uri": <endpoint>,
"isPrimary": true
}             
Output
201 Created
{
"id":"<Id of a webhook>"
}
Output for error cases
400 Bad Request
- When validation fails

Tables - Updating webhooks

Resource Template
>/webhooks/id}
Http Method PUT
Description

Allows update to URL value of a webhook. Allows to set IsPrimary value to true for a webhook which is not primary.

'isPrimary' is optional parameter and can only have 'true' value. 'uri' field is optional, and if it has a value, it will follow the validation rules for "Adding webhooks".

Input
{
"uri": <endpoint>,
"isPrimary": true
}
Output for successful retrieval
200 OK
Output for error cases
400 Bad Request - When validation fails

Tables - Deleting webhooks

Resource Template
/webhooks/{id}
Http Method GET
Description Allows deletion of a webhook.
Input
{
}
Output for successful retrieval
204 No Content
Output for error cases
400 Bad Request
 - When validation fails

Tables - Retrieving a single webhook

Resource Template
/webhooks/{id}
Http Method GET
Description

Allows retrieval of a webhook currently configured for a partner.

Input
{
}
Output for successful retrieval
200 OK
 { 
"id":"<Id of a webhook>"
"uri":"<webhook URL>",
"isPrimary":<true/false>,"createdOn":
"<timestamp when webhook was created>",
"lastUpdatedOn":"<timestamp when webhook was last updated>",
"lastEvent":
{
"pushedOn": "<timestamp when event was pushed>",
"eventType": "<one of the defined event types>",
"status":"<one of "Successful/Failed">"
}
}
Output for error cases
404 Not Found
 - if the partner currently has no webhook configured

Tables - Retrieving all webhooks

Resource Template
/webhooks
Http Method GET
Description Allows retrieval of a collection of webhooks currently configured for a partner.
Input
{
}
Output for successful retrieval
200 OK
{
webhooks": 
[
{ 
"id": "<Id of a webhook>"
"uri":"<webhook URL>",
"isPrimary":<true/false>,
"createdOn":"<timestamp when webhook was created>",
"lastUpdatedOn":"<timestamp when webhook was last updated>",
"lastEvent": 
{
"pushedOn":"<timestamp when event was pushed>",
"eventType": "<one of the defined event types>",
"status": "<one of "Successful/Failed">"
}
}
]
}
Output for error cases
404 Not Found
 - if the partner currently has no webhooks configured

Handling Callbacks

It is the best practice to consider to handle received callback in asynchronous manner to reduce possibility of timeouts.

Another good practice is to make processing received event idempotent so if the same event is received more than once, subsequent processing won't create any unexpected side effects.

Callback will be considered as accepted if returned HTTP Status code is either 200 or 201. Any header values or payload in a response will be ignored. If another response's status code is received, WUBS will continue to send an event for a period of time and if this event is still not acknowledged, it will be put in the error queue on the WUBS side.