Using WebHooks

Essentials on Xena WebHooks.

Want to know when a partner’s address changes or when an order is created - Xena Webhooks can be one solution to these situations. Basically, you register either for all updates in your fiscal setup of a given type - or listen on a specific id. Whenever something is created/updated or deleted that matches your criteria, you get a push notification to the URI, you supplied including which Id and the type of event.

Then you decide whether to fetch the data using either OAuth 2.0 or API keys to get the actual data that changed. Prime candidates for using Webhooks could be:

• Updating stock count in a webshop whenever an article is sold or purchased in Xena

• Adding a customer to an email marketing platform when created/modified in Xena

• Updating budgeting systems whenever something is bookkept in Xena

• Etc.

WebHook fundamentals

A webhook consists of three things:

• Type The type of a WebHook defines what type of entity the webhook is triggered on. It could for instance be “Article”, then the webhook is triggered every time an article is “changed”.

• Id (optional) The Id of a webhook limit the webhook to only be triggered for a specific entity Id. So if the webhook type is “Article” and the webhook Id is “7”, then the webhook is only triggered when something happens to the article with Id=7. If no Id is specified on the webhook, it will be triggered on ALL actions on Articles such as creates, modifications, and deletions.

• Callback URI When the webhook triggers, this is the URL of the endpoint which is called by Xena with a HTTP POST. Within this HTTP POST is the WebHook Payload, so make sure your endpoint can handle it.

WebHook payload

A webhook payload consists of three properties and looks something like this:

{
 "EntityType": "Article",
 "EntityId": 7,
 "EntityEvent": "Updated"
}

The above event means that the article with id 7 has been updated. The entitytype is the same as specified in the webhook itself. The Id is always present(regardless of what you defined in the webhook). There are three different events: “Updated”, “Created” and “Deleted”.

WebHook endpoint response

Every webhook should ALWAYS return a successful response with HTTP200. The structure of the response should be:

{
 "Success": true
}

The webhook trigger will be considered “not successful" if the endpoint does not respond within 5 seconds, respond with anything other than HTTP200 or does not return the JSON data above.

Activating a webhook

Using webhooks is very easy. They can either be created from the developer section or created via the API (eg. when an app is activated by the user). The WebHook API is found on the URL.

WebHook final thoughts

• Depending on the amount and type of webhooks you create, the webhooks can lead to quite a few requests. Make sure your system can handle the load!

• If your webhook endpoint does not respond within 5 seconds, it will be marked as “failed”.

• If your webhook endpoint does not respond with a HTTP200 response containing the proper response, the request will be marked as “failed” .

• If there are more than 10 failed webhook triggers within a 10-minute period, the webhook will be disabled for 1 hour to prevent Xena from DDOS’ing your system.