Working with Webhooks

In order to start receiving webhooks events in your app, you first need to create an HTTP endpoint for Claims Manager to send the webhook data to. You can setup one endpoint to handle several different event types, or setup multiple endpoints to handle each individual event type that you are interested in subscribing to.

Your endpoint should be publically accessible, and for the live environment must be secured with HTTPS (you can use plain HTTP in the test environment if you do not have an SSL certificate installed for your development/testing environment). It should accept an HTTP POST request whose body will be the webhook payload in JSON format. You must ensure that you respond to each request quickly with a successful status code (2xx).

Example endpoint

This code snippet is an example webhook endpoint written in node.js. This is a very basic example of receiving the webhook, determining the type and then responding with a successful response.

const express = require('express');
const bodyParser = require('body-parser');
const app = express();

app.post('/api/webhook', bodyParser.raw({inflate:true, limit: '100kb', type: 'application/json'}), (request, response) => {
  const webhook = request.body;

  // Handle the webhook
  switch (webhook.event) {
    case 'Event':
      const eventEntry = webhook.data;
      // handle Event webhook data here
      break;
    case 'Transaction':
      const transaction = webhook.data;
      // handle Transaction webhook data here
      break;
    default:
      console.log('Unknown webhook event $(webhook.event)');
  }

  // Return a successful response
  response.json({received: true});  
});

app.listen(8000, () => console.log('Running on port 8000'));

Once you have your endpoint(s) setup, you need to register them in Claims Manager. This can be done via the Webhooks endpoint in the Claims Manager API. You need to tell us the URL and any authorization header information you want us to include in the request. Once you have registered the webhook endpoint, you are ready to subscribe to any events you wish to receive from Claims Manager. Each webhook endpoint can have multiple different subscriptions, refer to the Webhook Events section for information about the various different events that you can subscribe to. Once you know which events you want to subscribe to, have a look at the Subscriptions page to see how to create the subscription. Be sure to also check out the Filters page to see how you can limit what events you receive for a given subscription, and the Webhook Security page to ensure you are following security best pratcises.