Webhook

Table of contents

Webhook

Overview

Webhooks allows canD Apps to receive real-time updates and react to specific events, enabling event-driven interactions. For example, when a user’s article receives a certain number of likes, the canD app for membership management can use this information to award points to the author and send notifications.

Configuring a webhook

To configure a webhook for the canD App, you should visit the canD App’s settings page and set the Webhook url to the canD App’s url to receive events. For now the url should be enough complicated so that others can’t guess and call it with fake data.

Webhook events are defined as an OAuth2 scope that starts with webhook:. List the scopes that match with required webhook events and include these in the authorization endpoint url. Once a community admin authorizes this setup, canD App will reveive HTTP requests when those events occur. To subscribe additional events, add the corresponding scopes for these new webhook events to the authorization request and have the community admin reauthorize.

Handling webhook events

A webhook event is an HTTP request whose method is POST and has a JSON body. As an HTTP server the canD App can just read the request body and end the response, performing some business logic.

Webhook event body

Field	Type	Description
`module`	String	The canD module id such as `MOIM`.
`type`	String	The webhook event type like `product.created` defined in the canD Module.
`context`	Object	The context object for the webhook event. See the below for the details.
`payload`	Object	The payload object for the webhook event. It depends on each webhook event. (Webhook Payload)

Webhook event context

Field	Type	Description
`originCommunityId`	String	The id of the origin community whose one of children is the community.
`userId`	String	The id in the origin community of the user.
`communityId`	String	The id of the community where the event occurs.
`profileId`	String	The id in the community of the user who performed the action to trigger the event.

Example handler

A typical webhook handler written in Node.js web framework Express would look like this:

app.post('/webhook', (req, res) => {
  res.end();

  const {module, type, context, payload} = req.body;

  switch (`${module}:${type}`) {
    case 'MOIM:product.created': {
      const botAccessToken = await BotAccessToken.findByCommunityId(context.originCommunityId);

      // Handle the event
      break;
    }
    default:
      console.warn(`No case statement for ${module}:${type} event whose context is ${JSON.stringify(context)} and payload is ${JSON.stringify(payload)}`);
      break;
  }
});

Testing webhook handler

To test webhook handlers in local without deployment, you can use services below to expose local servers to the internet. These services include:

Note that any data from canD to your local and vice versa are exposed to these services. You should avoid exposing sensitive data and rotate secrets.

Webhook Payload