Setting up webhooks

Setting up a webhook involves a multi-step process. It includes identifying your desired trigger-event, creating a webhook endpoint, setting up a webhook subscription, and enabling your application to monitor and respond to the webhook.

Follow the steps below to set up a webhook:

1. Identify your desired event type that will act as the trigger to initiate the webhook. A list of available events types can be found in the Webhooks Overview page.
2. Set up an HTTPS URL that is accessible from the public web. This URL will act as the webhook endpoint where the Strike API will send the webhook when the trigger-event occurs. For testing purposes, you can use tools like RequestBin, Webhook.site or Typedwebhook.tools and use the Strike API Explorer to trigger an event.
3. Create a subscription for your desired event type by using the create subscription endpoint. When creating the subscription, you must specify your desired trigger-event type from step 1, your webhook endpoint URL from step 2, the API version, and a secret that will be used by the Strike API to sign each webhook request. The secret can be any arbitrary string, ranging from 10 to 50 characters long, and should be kept safe and private. It is best practice for your application to use signature verification using the secret, to ensure the authenticity of incoming webhooks. If the secret is compromised, change it by using the update subscription endpoint.
4. Set up your application to be listening on your webhook endpoint that was set up in step 2. When a webhook is sent to that URL, your application must receive it, check the eventType, parse the JSON payload, verify the webhook’s signature, and return a 2xx response status code. Please note that if the response takes longer than 5 seconds, the webhook request will be canceled, treated as failed, and scheduled for retry per our retry policy. It’s best to avoid executing complex logic when receiving webhooks to ensure that your application responds as soon as possible.

Once these steps have been completed, your application will be ready to begin using webhooks. When the trigger-event occurs, the Strike API will deliver the webhook to your specified webhook endpoint URL, at which point your application will verify and process it before responding with a 2xx response code.

Please note that webhooks do not contain the data of the trigger-event, rather they simply notify that the trigger-event has occurred. To retrieve specific details for the trigger-event, you must make a corresponding API request to retrieve that information.

Below is an example of a webhook’s JSON payload:

Example webhook JSON payload:

{
  "id": "245e40d8-f197-411c-8f20-a326d08da402",
  "eventType": "invoice.updated",
  "webhookVersion": "v1",
  "data": {
    "entityId": "602cc206-6b4a-42dd-bc89-9a534bb04034",
    "changes": [
      "state"
    ]
  },
  "created": "2009-01-03T18:15:00+01:00",
  "deliverySuccess": true
}

In the above example, the trigger-event was an invoice being updated. In this webhook, the id is the event’s ID and the data is the content of the webhook, containing both the entityId (the ID of the updated invoice) and the changes array specifying what has changed (the state of the updated invoice).

You can use one webhook endpoint URL to be notified of multiple different event types at once, or create up to 50 individual endpoints for specific events. Please be aware that the Strike API may deliver a webhook more than once, so your application must be able to accommodate redundant webhooks for the same event occurrence.