Get Started

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.