Create and Publish a WebSub/WebHook API

This tutorial will guide you to create a WebHook API which will listen to the issues created in GitHub and send you a notification upon creation. Follow the instructions in this tutorial to design and publish a WebSub/WebHook API, and register a WebHook for it.

The tutorial demonstrates a simple WebSub/WebHook API that monitors your GitHub repository for new issues, and receives events when an issue is created.

Step 1 - Design a WebSub/WebHook API

1. Sign in to the Publisher.

   https://<hostname>:9443/publisher

   For testing purposes, you can use https://localhost:9443/publisher and admin as the username and password.

2. Click CREATE API, go to Streaming API, and Click WebHook API.

   

   Note

   The CREATE button will only appear for a user who has the creator role permission.

3. Enter the details of the new WebSub/WebHook API.

   Field	Sample value
   Name	RepoWatcher
   Context	/repo-watcher
   Version	1.0.0
   Protocol	WebSub

4. Click CREATE.

   The overview page of the created WebSub/WebHook API appears.

   

5. Add a topic to the WebSub/WebHook API.

   1. Click Topics and navigate to the Topics page.

   2. Click Add Topic, add a topic with the name /issues, click Add, and finally click Save.

      

6. Generate a secret.

   1. Expand the Subscription Configuration section in the Topics page.

      

   2. Click Enable to enable secret generation.

   3. Select SHA1 as the Signing Algorithm.

   4. Click Generate to generate a secret.

      

   5. Copy the generated secret.

      Let's refer to the generated secret as [generated_secret].

   6. Click Save.

7. Attach business plans to the WebSub/WebHook API.

   1. Click Subscriptions and navigate to the Business Plans page.

   2. Select AsyncWHGold and click on Save.

      

Now, you have created and configured the WebSub API (WebHook API) successfully.

Step 2 - Forward a Public URL

A public URL should be forwarded to localhost:9021, so that your local server can be accessible to the WebHook provider (GitHub). ngrok can be used for this purpose.

1. Download ngrok, and start it.

   This will forward a public URL to localhost:9021.

   ./ngrok http 9021
   

2. Copy the HTTP URL that is forwarded to http://localhost:9021, as shown in ngrok's terminal.

   In the following example, it is http://3b1*******c9.ngrok.io.

   Forwarding                    http://3b1*******c9.ngrok.io -> http://localhost:9021
   Forwarding                    https://3b1*******c9.ngrok.io -> http://localhost:9021
   

Step 3 - Add a WebHook to your GitHub Repository

Note

You can use an existing GitHub repository of yours, or create a new one for this purpose.

1. Go to Settings of your GitHub repository.

2. Click WebHooks, navigate to the WebHooks page, and click Add WebHook.

   

3. Configure the WebHook.

   1. Go back to the WSO2 API Publisher, click Topics to navigate to the Topics page, and expand the /issues topic.

   2. Copy the Callback URL.

      https://{GATEWAY_HOST}:9021/repo-watcher/1.0.0/webhooks_events_receiver_resource?topic=/issues
      

   3. Go back to your GitHub repository's WebHooks page.

      Provide the following values.

      Field	Value
      Payload URL	http://3b1*******c9.ngrok.io/repo-watcher/1.0.0/webhooks_events_receiver_resource?topic=/issues This is obtained by replacing https://{GATEWAY_HOST}:9021 part of the /issues topic's Callback URL, with the forwarding HTTP URL from ngrock (For example, http://3b1*******c9.ngrok.io).
      Content type	application/json
      Secret	[generated_secret] This is the secret you obtained from the Subscription Configuration section of the WebSub/WebHook API's Topics.
      Which events would you like to trigger this WebHook?	Select Let me select individual events, and check Issues.

      

   4. Click Add WebHook.

Step 4 - Publish the WebSub/WebHook API

1. Go to WSO2 API Publisher.

2. Click Lifecycle to navigate to the API lifecycle.

3. Click PUBLISH to publish the API to the API Developer Portal.

4. Click Deployments to navigate to the Deployments page.

5. Click Deploy New Revision.

6. Select Production and Sandbox, choose localhost as the VHost, and click on Deploy.

   

Step 5 - Create a Callback URL

1. Go to https://webhook.site.org.

2. Click New, leave the default values, and click Create.

   A unique URL will be created for you.

   

3. Click Copy to clipboard which is next to Your unique URL.

   

4. URL-encode the unique URL that you copied.

   Let's refer to the URL-encode unique URL as [encoded_hub_callback].

5. Leave the webpage open as you will need to come back to it again.

Step 6 - Invoke the WebSub/WebHook API

1. Sign in to the Developer Portal.

   https://<hostname>:9443/devportal

   For testing purposes, you can use https://localhost:9443/devportal and admin as the username and password.

2. Click on the WebSub/WebHook API.

   The API overview appears.

3. Subscribe to the API.

   1. Click Subscriptions to go to the Subscriptions page and click SUBSCRIPTION & KEY GENERATION WIZARD.

      This wizard takes you through the steps of creating a new application, subscribing, generating keys, and generating an access token to invoke the API.

      Note

      You can use any application (e.g., JWT or OAuth) to subscribe to the API.

      

   2. Copy the authorization token that appears, and click FINISH.

      

4. Try out the operations.

   1. Subscribe to the /issues topic.

      1. Subscribe the callback URL with the /issues topic by executing the following cURL command. Replace [encoded_hub_callback] and accesstoken with the values you have obtained.

         curl -X POST 'http://localhost:8280/repo-watcher/1.0.0' -H 'Content-Type: application/x-www-form-urlencoded' -d 'hub.topic=%2Fissues' -d 'hub.callback=[encoded_hub_callback]' -d 'hub.mode=subscribe' -d 'hub.secret=newValue' -d 'hub.lease_seconds=50000000' -H 'Authorization: Bearer [accesstoken]'
         

      2. Click Subscriptions to go to the Subscriptions page of your application in the Developer Portal.

      3. Click the WebSub API's subscription entry. This will list down the subscription that you just made.

      4. Go to your GitHub repo and create a new issue. This will trigger the GitHub WebHook you have created.

      5. Go back to the webpage at https://webhook.site.org, where you created the callback URL. A new request which denotes the issue creation would have appeared.

         

   2. Unsubscribe from the /issues topic.

      Unsubscribe the callback URL from the /issues topic by executing the following cURL command.

      Replace [encoded_hub_callback] and accesstoken with the values you have obtained.

      curl -X POST 'http://localhost:8280/repo-watcher/1.0.0?hub.callback=[encoded_hub_callback]&hub.mode=unsubscribe&hub.secret=newValue&hub.lease_seconds=50000000&hub.topic=/issues' -H "Authorization: Bearer [accesstoken]"
      

You have successfully created and published your first WebSub/WebHook API, subscribed to it, obtained an access token for testing, created a subscription to a WebHook, and tested your API with the access token.

Note

WSO2 API Manager also supports subscription requests with application/x-www-form-urlencoded content type, which adheres to the standards specified by W3C. This allows you to pass the hub parameters in the request body by passing them as form data. API Manager also supports optional subscriber verification of intent for this type of requests. This can be enabled by adding the property enableSubscriberVerification with the value set to true at the Publisher Portal. The default value is set to false. In later versions, this can be directly enabled by changing the WebSub Configurations in the API Configurations panel.