Webhooks

Webhooks

Thanks to webhooks, investigation workflow is improved by integrating the results of Linkurious-generated alerts into a third party case management system in real time. You can also subscribe to events to monitor usage of Linkurious’ alert system within a third party dashboarding tool.

Webhook events and payloads

You can create webhooks that subscribe to the events listed below.

To limit the number of HTTP requests made to your server, take care to subscribe only to the events you wish to use.

Case created

This event will be triggered when an alert create a new case.

{
  eventType: 'newCase',
  sourceKey: 'b4675b85',
  data: {
    alert: {
      id: 1,
      title: 'Example alert',
      description: 'This is an example'
    },
    case: {
      id: 2,
      createdAt: '2024-02-26T15:07:20.333Z',
      target: {
        nodes: ['1', '2', '3'],
        edges: ['4', '5']
      },
      url: 'https://example.com/alerts/1/case/2'
    }
  }
}

Case updated

This event will be triggered when a new match is found for an existing case.

{
  eventType: 'newMatch',
  sourceKey: 'b4675b85',
  data: {
    alert: {
      id: 1,
      title: 'Example alert',
      description: 'This is an example'
    },
    case: {
      id: 2,
      createdAt: '2024-02-26T15:07:20.333Z',
      updatedAt: '2024-02-27T13:00:49.020Z',
      target: {
        nodes: ['1', '2', '3'],
        edges: ['4', '5']
      },
      url: 'https://example.com/alerts/1/case/2'
    }
  }
}

Case status changed

This event will be triggered when a user will change the status of a case.

{
  eventType: 'caseStatusChange',
  sourceKey: 'b4675b85',
  data: {
    alert: {
      id: 1,
      title: 'Example alert',
      description: 'This is an example'
    },
    case: {
      id: 2,
      createdAt: '2024-02-26T15:07:20.333Z',
      updatedAt: '2024-02-27T14:09:30.207Z',
      status: "confirmed",
      url: 'https://example.com/alerts/1/case/2'
    },
    user: {
      id: 3,
      username: 'john.doe',
      email: 'john.doe@linkurious.com'
    },
    comment: 'The case is confirmed!'
  }
}

Managing webhooks

You can subscribe, unsubscribe and list the configured webhooks by using API.

Only users with the built-in Admin role can manage webhooks.

POST /api/admin/webhooks : Create a webhook. Webhooks can subscribe to one or more events for one or many datasources.

GET /api/admin/webhooks : Return the list of all webhooks.

DELETE /api/admin/webhooks/:webhookId : Delete a specific webhook.

You can find all details on these API in the Rest-client documentation.

You can also install and use the Webhook Manager from the official plugins to easily use the above APIs.

Handling deliveries

To handle deliveries, you must configure a HTTP endpoint that can handle POST requests and answer with a 2xx status response. The body of the POST request contains the payload of the event subscribed.

You should ensure that your server uses an HTTPS connection.

In order to give the recipient endpoint the ability to authenticate hook deliveries, a secret is attached to each webhook. This secret is used to compute the HMAC hex digest of the delivery payload, using the SHA-256 hash function. This HMAC is attached in the X-Payload-HMAC HTTP header (see https://nodejs.org/api/crypto.html##class-hmac).

Troubleshooting

Two specific API are available for you to test and ensure that webhooks and your integration are correctly configured.

POST /api/admin/webhooks/:webhookId/ping : Trigger a ping pseudo-event on a given webhook (details here)

GET /api/admin/webhooks/:webhookId/deliveries : Return the list of the deliveries for a given webhook (details here)