Tutorial: Webhooks

Serverless DatabaseNotifications Webhooks

Webcom provides a "webhook notification" function that allows an application to subscribe to a data node of the Webcom database and to trigger a notification towards a third-party server when some data under this node is updated.

Use-case examples:

  • a custom backend application can directly subscribe to some data and get notifications with incoming HTTP POST requests,
  • a mobile application can add a subscription on a specific path, which will notify a preconfigured “custom SMS gateway server” in order to send a SMS to the corresponding device.

Configuration of webhooks by the developer

Prepare a specific endpoint on your custom server

Webhooks are HTTP requests that will be sent to specific HTTP endpoints. Their message format is described below. For testing purpose you may use: the https://webhook.site/ service.

Webhook configuration

You can configure your webhooks on the notifications tab in the Webcom developer console.

You can also change webhook settings using the following REST API:

# SECKEY is a secret key of your application, you can get it from authentication tab of developer console.
# GET current settings
curl -X GET "https://io.datasync.orange.com/datasync/v2/<your-app-id>/settings"  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SECKEY" \
  | jq .

#Set a new webhook configuration
curl -X PUT "https://io.datasync.orange.com/datasync/v2/<your-app-id>/settings/webhooks"  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SECKEY" \
  -d '{"destinations":{"myWebhook":{"enabled":true,"subscribeDurationSeconds":3600000,"destinationUris":[{"uri":"https://webhook.site/<XXXX>","acceptAnyCertificate":false}],"headers":{"X-webcom-webhook-token": "bar"}}}}' 

#you can get current settings again to check  

Subscription

You may add subscriptions using the following API on the appropriate client SDK. In this example, we subscribe to the "child addition" and "child change" events (similar to the ones available for the real-time subscriptions) on the "one/child/where/to/subscribe" data node (replace “<your-app>” with your actual application identifier):

// Create a reference to a Webcom application
var ref = new Webcom("<your-app>");
var node = ref.child("one/child/where/to/subscribe");
// You MUST authenticate
ref.authAnonymously();
// Subscribe to the "child addition" and "child change" events on the node
var subscription = ref.subscribe(Webcom.Event.Child.Addition.Change, Webcom.Webhook("myWebhook", "a context"));
// The subscription object may be further used to cancel or update the subscription

Coming soon!
In the meanwhile, refer to the Android API reference

let node = Webcom.defaultApplication.dataService.node(for: "one/child/where/to/subscribe")
let descriptor = DataSubscriptionDescriptor(eventType: .child(addition: true, change: true, removal: false))
node.subscribeThroughWebhook("myWebhook", context: "a context", descriptor: descriptor) { result in
    switch result {
    case let .success(subscription):
        print("subcription succeeded")
        // subscription.cancel() // may be used to cancel the subscription
    case let .failure(error):
        print("subcription error:", error)
    }
}
#You first need to get a uid and webcom-token, for quick testing purpose you can use anonymous provider (you need to activate anonymous provider on your application):
curl -X POST "https://io.datasync.orange.com/auth/v2/<your-app>/anonymous/signin" | jq
WTOKEN=<the resulting token>
WUID=<the resulting UID>

#Webhook subscription
curl -X POST "https://io.datasync.orange.com/datasync/v2/<your-app>/subscriptions/$WUID?allowsUpdate=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WTOKEN" \
  -d '{"kind":"webhook", "mode":"childEvent", "childEventFilter":{"added":true, "removed":false, "changed":true}, "path":"/one/child/where/to/subscribe", "context":"a context", "destination":"myWebhook"}' \
  -v | jq .

#Get subscription information
SUBID=<found in content-location header of previous subscribe POST>
curl "https://io.datasync.orange.com/datasync/v2/<your-app-id>/subscriptions/$WUID/$SUBID" \
  -H "Authorization: Bearer $WTOKEN" \
  -v | jq .

You can now write some piece of data on the "one/child/where/to/subscribe" path of your Webcom application and check on that you receive the webhook notification.

Simulation

It is possible to test webhook reception using a specific REST API (replace “<your-app>” with your actual application identifier):

Example:

curl -X POST "https://io.datasync.orange.com/datasync/v2/<your-app>/webhookSimulations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SECKEY" \
  -d '{"destination":{"enabled":true,"subscribeDurationSeconds":3600000,"destinationUris":[{"uri":"https://webhook.site/<XXX>","acceptAnyCertificate":false}],"headers":{"X-webcom-webhook-token": "foo"}}}' \
  -v | jq .

Notification format

The notification message encoding is described below. Please note that if you use Android or iOS SDK, you don't need to decode it yourself, please see relevant sections (coming soon).

Data contained in notification has the following structure:

  • a data structured object field containing the event information and described below,
  • a context string field containing the context string given at subscription,
  • a auth (event) object field, containing the authentication token payload data of the user that added the subscription.

The event itself has the same structure than mobile push notification events.