AppStax Webhooks

Getting Started

Webhooks are ServerCode API calls registered to be called every time an object is created, updated or deleted. To use webhooks you need to do three things:

  • Launch a ServerCode container.
  • Register the webhooks in the Admin UI.
  • Deploy your server code with some API handlers.

Types of webhooks

There are six types of webhooks:

  • beforeCreate
  • afterCreate
  • beforeUpdate
  • afterUpdate
  • beforeDelete
  • afterDelete

Webhooks are registered per collection. Different collections can have different number of webhooks registered.

As you can see, there are three before* webhooks, and three after* webhooks. The following table explain the meaning of each, and describe when and how they are executed.

Once registered for a collection, each webhook is called automatically by the AppStax platform.

Webhook Explanation Synchronicity
beforeCreate Called before the object is created Synchronous
afterCreate Called after the object is created successfully Asynchronous (fire-and-forget)
beforeUpdate Called before the object is updated Synchronous
afterUpdate Called after the object is updated successfully Asynchronous (fire-and-forget)
beforeDelete Called before the object is deleted Synchronous
afterDelete Called after the object is deleted successfully Asynchronous (fire-and-forget)

Synchronous execution

before* webhooks are all executed synchronously, which means that the AppStax server will wait for the call to the server code to return before continuing the processing of the request. If the server code request handler returns an HTTP error code (400 and above), the processing will be aborted, and the object will not be created/updated/deleted.

Example use cases for before*-webhooks:

  • Data validation: making sure the object properties all have legal values
  • Pre-population: filling in or calculating a property value based on business logic.

Asynchronous execution

after* webhooks are all executed asynchronously, and only if the prior create/update/delete operation was successful. Asynchronous here means that the call to the webhook is queued by AppStax, and control is returned immediately to the client making the call. If for some reason the platform was unable to call the server code webhook handler, AppStax will try again later. A total of 10 attempts will be made, 5 minutes apart. If the webhook handler has not been successfully called by 10 attempts, the call will be removed from the queue.

Example use cases for after*-webhooks:

  • Data integration: data saved to AppStax can be saved to non-AppStax systems, e.g., internal corporate systems such as SAP, Microsoft CRM, Oracle etc.

Implementing webhook API handlers

In the AppStax Admin UI you can specify the URL endpoint for a webhook. Whenever an object is created, updated or deleted the corresponding handler is called by the backend.

The following are the requirements for each handler:

  • The HTTP method for the handler must be PUT.
  • Like all ServerCode API handlers, the URL endpoint must start with /api, so e.g., a beforeCreate handler is /api/myhandler

An example Express handler for a beforeCreate webhook for a collection games could be:

var app = require('express');
var bodyParser = require('body-parser');
app.use(bodyParser.json())
app.put("/api/games/beforeCreate", function(req, res) {
    console.log("collection is: " + req.body.collection)
    console.log("event is: " + req.body.event)
    console.log("object is: " + JSON.stringify(req.body.event))
})

Explore

Learn more about using ServerCode API calls here:

ServerCode