Webhooks

Webhooks

Webhooks use the same mechanism as polling, except that pages are pushed from server to client, rather than requested explicitly by the client from the server.

The client registers an endpoint with the server, and the server repeatedly sends subsequent pages to the client. Using the same paging features as with polling allows the server to batch items to increase throughput.

When sending a particular page to the client the server is expected to wait for a successful acknowledgement of the page before sending the next page. If sending of a page fails that page should be continuously retried with an exponential backoff. The server should only proceed to the following page after successfully sending the previous one.

Note that during a full cache refresh the client will page the server for all data, and may simultaneously be receiving webhook requests from the client. Using the timestamp of each record to ensure records are only updated with newer data, the client is able to perform both the full cache refresh and receive webhook requests simultaneously. Alternatively the client can choose to drop webhook requests until its full cache refresh is complete, which should trigger the exponential backoff behaviour from the server, ensuring a good crossover in items between the end of the cache refresh and the webhook updates resuming.

Webhooks Example

Example payload for the webhook:

/putSessions
-> { items: [{
       state: 'updated',
       kind: "session",
       id: "{c15814e5-8931-470c-8a16-ef45afedaece}",
       modified: Date(a),
       data: {
           lat: 51.5072,
           lng: -0.1275,
           name: 'Acrobatics with Dave',
           clubId: "{fc1f0f87-0538-4b05-96a0-cee88b9c3377}"
       }
    },{
       state: 'deleted',
       kind: "session",
       id: "{d97f73fb-4718-48ee-a6a9-9c7d717ebd85}",
       modified: Date(b)
    }]
}

Note that the "next" from the response is not required here. Instead, from and after should be stored for each client of the server, in order that the server is able to send the relevant next page to each client.

Multicast Scenarios

When a number of clients are registered, the server can aggregate the demand - synchronising the responses and pushing out a single page to all clients.