Using Webhooks: n8n Setup

Synopsis

Your WarmHub repos have the ability to emit communications about certain events happening in the repo. This is helpful if you would like to connect custom automations to your repo. n8n is a powerful tool for creating these automations, and can play a key role in easily building external integrations into your WarmHub repo. We will review one example scenario of how to link one set of events in your repo to n8n.

Setup

You will need a repo with types. In this example, we will use the the types from the chemical elements repo in the WarmHub Labs Chemical Elements repo.

Additionally, you will need a n8n account which you can create at https://n8n.io. This guide will work for either the self-hosted or cloud versions of n8n.

Setting Up Your Repo

We will begin by setting up a repo with some types. Create a new repo. Then, go to the "Types" page. In the top right, select "Import Types," and search for "Chemical Elements" from the warmhub-labs organization.

Click the "+" to import the types from the Chemical-Elements repo into your repo.

Now, you should see the types from the Chemical-Elements repo in your repo, if the checkbox is selected to show the types from that repo. If you would like to hide them, you may uncheck the checkbox, but we will leave the types imported from this repo visible for now.

Creating a Workflow in n8n

In your n8n workspace, create a new workflow. On this new page, click on the "Add first step" button in the center of the screen. Then, add a "Webhook" node:

After adding the Webhook node, we will do two things to set it up:

Copy the webhook URL by clicking on the field.
1. For now, we will just use the test URL. For more about the difference between the test and production webhook URLs, please refer to n8n's documentation here.
Change the HTTP method to POST.

Creating a Webhook in WarmHub

Only repo owners have permissions to configure webhooks. Repo members are not able to view the Events or Webhooks pages.

Since you created the repo, this will not be an issue for this guide.

Now, return to your WarmHub repo. In the side navigation, select the "Webhook" tab. Select "Create Webhook."

This will launch a modal where you can configure your webhook. Now, enter a name for your webhook, and paste in the URL you obtained from n8n in the last step.

We will have this webhook trigger on the "Commit Created" type, and set the eligible (WarmHub) types to "All." After setting up your webhook, select "Create." Your webhook will now be active.

Testing the Webhook

The webhook we configured above will trigger every time a commit is made in your repo, on any WarmHub type to which the commit may be relevant.

Tracing Events in n8n

n8n provides powerful features for visualizing the data flow both within the workflow and into and out of any external sources, such as WarmHub. To test the function of this workflow:

Select "Execute workflow" in n8n

Post any commit in WarmHub. For this example, we will post a Chemical Element (Article)
- Either
  - navigate to the Types page of your repo, and select the "Commit Instance" button in the row,
  - or navigate to the About page repo, select "Commit Data," select the "Add new data to this repo" commit type, and the "Chemical Element" WarmHub type
- Regardless

Return to n8n. After a moment, the test workflow should complete and the data from the webhook will populate into your input Webhook node. After clicking into the Webhook node, it should look similar to the following:

In this particular webhook type, note that the body which the webhook returns is in the following format:

"body": {
    "payload": [the $wref of your commit]
}

If you navigate to the particular URL received by the webhook, you will see the addition of one Chemical Element which you made through your commit to your repo.

Tracing Events in WarmHub

Reminder: Only owners of the repo are able to access the Events and Webhook pages of your repo.

You can also view the events involved in triggering the webhook in the Events page of your repo.

The first four rows in the above screenshot represent the details behind the commit you just made. Note the identical Correlation ID among the events, as the events are all related to one action.

In chronological order (reversed from what is presented above):

CommitCreated: This is directly triggered by your commit, and is the event which we configured the webhook to act upon. This event occurs one time whenever you create a commit (either an addition, revision, or retraction).
InstanceAdded: This is triggered by the addition of the instance to your repo. Since the commit builder only commits one addition, revision, or retraction at once, there is only one event here. However, if you post a commit to WarmHub using another method, there can be multiple InstanceAdded, InstanceRevised, and/or InstanceRetracted events per CommitCreated event.
WebhookQueuedForCommtiCreatedEvent and WebhookCalled are informational messages that WarmHub has correctly processed and sent the relevant webhook events.

It is also possible to resend events. This is useful if you have lost the webhook data in your n8n workflow, and would like to have that data sent once again so that it is available.

In this scenario, first select "Execute workflow" in n8n. To access the resend functionality, select the "Details" icon in the row for that table.

Then, in the top right corner of the popout, select "Resend." After a moment, the n8n input node should populate with the data from your selected event. Note that the Events page in WarmHub will not refresh automatically, so to view the resent event, select a later end bound in the date picker and select "Run."