WebHooks

Blueprint for push endpoint registration

Goal: Have a way to notify clients when "something" happens.

1. In-app notifications: I'm a client and I need to know when new data has been added to the collection
2. Service integration: I'm a service and I want to know when new data has been added to the collection

In both cases, the client/service registers on the Kinto server.

Flow

If a recipient wants to be notified, it registers its webpush URL on a /notifications/webpush endpoint. The /notifications prefix is useful in order to have multiple notification systems (webpush is one but there could be others i.e emails or webhooks).

This information expires after a duration defined on the server (1 day for webpush, never for webhooks).

webhooks and webpush notification can only be put on users, for anonymous user a basicauth random token can be used.

Request / Response flow

Depending its need, the client asks to be notified when some modification occurs. In order to do so, it can ask to be notified on different endpoints (buckets, collections, records) and for different operations ("read", "write")

The notification endpoint is global for a user and all her notification rules are available here.

Get the user subscriptions list

GET /notifications/webpush
< Request <

> Response >
{
  data: [{
    "subscription": {"endpoint":"https://updates.push.services.mozilla.com/push/v1/gAAAAABXhkuIG...DnyV8iUiX3lVm","keys":{"auth":"by64sz1qJT...xl_g","p256dh":"BGRz...AX6EiUPuDefoC4"}}
    "triggers": {
      "/buckets/blocklists/collections/*/records": ["write"],
    }
  }]
}

Add a new user subscription

POST /notifications/webpush
< Request <
{
    "push": {"endpoint":"https://updates.push.services.mozilla.com/push/v1/gAAAAABXhkuIG...DnyV8iUiX3lVm","keys":{"auth":"by64sz1qJT...xl_g","p256dh":"BGRz...AX6EiUPuDefoC4"}}
    "triggers": {
      "/buckets/blocklists/collections/*/records": ["write"],
    }
  }

> Response >
{
  data: {
    "id": "a7546569-7583-4939-b9c9-71acb9321f82", 
    "last_modified": 1469023718589,
    "push": {"endpoint":"https://updates.push.services.mozilla.com/push/v1/gAAAAABXhkuIG...DnyV8iUiX3lVm","keys":{"auth":"by64sz1qJT...xl_g","p256dh":"BGRz...AX6EiUPuDefoC4"}}
    "triggers": {
      "/buckets/blocklists/collections/*/records": ["write"],
    }
  }
}

Delete an user subscription

DELETE /notifications/webpush/a7546569-7583-4939-b9c9-71acb9321f82
< Request <

> Response >
{
  data: {
    "deleted": true, 
    "id": "a7546569-7583-4939-b9c9-71acb9321f82", 
    "last_modified": 1469023786584
  }
}