What is a webhook?
Webhooks are callbacks made by Champ to an internet accessible endpoint. Endpoints are used for communication between web applications. This feature is an advance feature and this documentation is intended for developers.
Currently, Champ supports two (2) types of webhooks:
- When a new topic is created
- When a new post is created
Here are some examples:
If a user creates a new topic, two webhooks are sent: one for the topic and one for the post.
If a user replies to a post, only one webhook is sent.
No webhooks are sent for editing posts or topics.
How Champ webhooks work
Champ webhooks are sent to specified endpoints (which you define in the app’s dashboard) when either posts or topics are created.
You can customize the following:
- Headers sent in the POST or PUT request
- Data payload
Webhooks are sent with a special header called X-Champ-Hmac-SHA256.
We use a shared secret to digitally sign the webhook request so you can compare the value (using the shared secret) that you generate on your server.
Note: Do not expose this shared secret publicly anywhere.
You do not need to use the shared secret to use webhooks. However, your system may be subjected to fake requests should a malicious attack discover your endpoints.
It is recommended you take a look at verifying webhooks on the Shopify documentation. Champ uses the same mechanism to digitally sign the HTTP request, so the information on Shopify’s documentationapplies here as well.
Creating a webhook
To create a webhook, click on Webhooks from the app’s dashboard:
You’ll see a link button to add a new webhook, your shared secret (which you can use to verify that the webhooks are coming from Champ), and the list of webhooks you’ve created:
To get started, click on Create new webhook. There, you’ll be presented with a screen to enter the information that is required:
- URL endpoint
- Choose PUT or POST request
- Topic
- Data payload
A dropdown is also available to enable/disable the webhook. As well, you can add custom headers to the HTTP request.
Once you’ve created a webhook, you’ll also see a link on the upper right hand corner (in red text) to delete the webhook.
The URL of the endpoint must be unique. If there’s another webhook with the same URL, validation will fail and the webhook will not be saved.
The data payload is the HTTP body that is sent with the webhook request. The webhook is sent in JSON format only, and the data payload represents a JSON data object with some customizations available for you. You can use standard Liquid syntax to add conditional statements. There are also a few Liquid objects that you can use. These are as follows:
- user.id – the Shopify customer ID
- user.email – customer email
- topic.id – the unique topic ID
- topic.title – the topic title
- topic.url – the direct forum URL to the topic
- topic.forum_title – the forum title which the topic belongs to
- post.id – the unique post ID
- post.title – the post title
- post.content – the HTML rendered content of the post
- post.topic – the Topic Liquid object as described above
Modifying a webhook
You’re able to modify the webhook by going to the Webhooks section of the dashboard and clicking Edit webhook on the webhook you want to modify.
Remember to click Save.
Deleting a webhook
To delete a webhook, select Edit webhook of the webhook you want to delete.
On the upper right hand corner, there’s a link (in red text) to Delete webhook. A confirmation popup will appear to ask if you are sure you want to delete.
Verifying webhooks
It is recommended that if the webhooks are used to modify a customer’s information in a material manner that you verify the requests coming from Champ to ensure that no malicious actors are using your API endpoints maliciously.
Webhooks are sent with a special header called X-Champ-Hmac-SHA256 which contains a signature. Generate, using the shared secret (available by going to the Webhooks section from the dashboard) and generating a Base64-encoded header with the HTTP request body.
Here’s an example code in Ruby of how to generate this value and compare them: