Configuration

Setting up a webhook

To set up a webhook, you can create one in the Extend dashboard settings under the “Developer” tab

Global webhooks

To receive events for webhooks you need to subscribe to events. From the main “Developer” tab when creating/updating a webhook endpoint you can subscribe to the GLOBAL event types. These events are not associated with a specific workflow or processor and are global to your workspace.

See the Events section for more details on the different event types you can subscribe to.

Workflow specific subscriptions

After you have created one or more webhook endpoints from the “Developer” tab, you can subscribe to events for specific workflows by navigating to the desired workflow(s) and opening the “Webhook Subscriptions” menu.

Then you can create new subscriptions for the desired endpoints and event types.

Once subscribed, you will start to receive events to the specified webhook endpoint based on the selected event types each time you run a file(s) through that workflow.

See the Events section for more details on the different event types you can subscribe to and the shape of the payload for each event type.

Processor run specific subscriptions

You can also subscribe to events for specific processor runs. This is necessary if you are running processors directly and not via a workflow.

To start, navigate to the Deployment tab of the given processor in Studio and click the “Create Webhook Subscription” button.

Next, you can select the desired event types you would like to subscribe to and assign the webhook endpoint you would like to receive events at.

Finally, click create and then you will see the enabled webhook subscription:

Verifying webhook requests from Extend

Extend will sign each webhook request using a secret unique to the webhook. You can use this signature along with the timestamp to verify that the request is coming from Extend as well as protect against replay attacks.

Steps to verify a webhook request from Extend

At a high level, the steps to verify a webhook request from Extend are

1. Retrieve the timestamp of the request from x-extend-request-timestamp, the body of the request, and the signing secret associated with the webhook.
2. Concatenate the timestamp and request body using the following format: v0:${timestamp}:${requestBody}
3. Compute a HMAC 256 digest on the resulting string using the signing secret as the key. The secret can be found in the webhooks table under the “Developer” tab

4. Compare this digest with the signature provided in x-extend-request-signature. If they are equal, then the request is verified to be from Extend.

Here is pseudocode in Javascript to perform the verification:

  import crypto from "crypto";

  // retrieve from x-extend-request-timestamp
  const timestamp = 1707777128;

  const requestBodyString = JSON.stringify(request.body);

  // retrieve from the webhook details on the "Developers" tab
  const signingSecret = "wss_C...l";

  const message = `v0:${timestamp}:${requestBodyString}`;
  const expectedSignature = crypto.createHmac("sha256", signingSecret).update(message).digest("hex");

  // retrieve from x-extend-request-signature
  const receivedSignature = "d3a8d5de6d463023b052ee1eb8e7f247dce6bf90b4a3e1117b4922afdc90029b";

  if (expectedSignature === receivedSignature) {
    // proceed
  }