Develop a Webhook¶
Choreo allows developers to design high-quality webhooks. To explore this capability, let's consider a scenario where a team of software engineers in an organization should be notified via email whenever someone creates a GitHub issue with the bug
label in a specific repository.
In this tutorial, you will address the requirement by doing the following:
- Create a webhook by connecting to a forked GitHub repository where you have the webhook implementation that addresses the described requirement.
- Deploy the webhook to the development environment.
- Modify the webhook implementation to connect the webhook to GitHub, enabling it to act in response to selected GitHub-related events.
- Test the webhook.
- Promote the webhook to the production environment.
Prerequisites¶
-
If you're signing in to the Choreo Console for the first time, create an organization:
- Go to https://console.choreo.dev/ and sign in using your preferred method.
- Enter a unique organization name. For example,
Stark Industries
. - Read and accept the privacy policy and terms of use.
- Click Create.
This creates the organization and opens the Project Home page of the default project created for you.
-
Fork the Choreo samples repository, which contains the sample integration for this guide.
Step 1: Create a webhook component¶
To create a Webhook component, follow these steps:
- Go to https://console.choreo.dev/ and sign in using your preferred method.
- If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
- Click the Webhook card.
- In the Create a Webhook pane, specify a name and description for the component.
- Go to the GitHub tab.
-
Click Authorize with GitHub to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the Choreo GitHub App.
Alternatively, paste the Choreo samples repository URL in the Provide Repository URL field. However, enabling Auto Deploy requires authorizing the repository with the Choreo GitHub App.
Note
The Choreo GitHub App requires: - Read and write access to code and pull requests. - Read access to issues and metadata.
You can revoke access at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository.
-
Select the Access Mode depending on your requirement.
-
Enter the following information:
Field Description GitHub Account Your account GitHub Repository choreo-samples Branch main Buildpack Ballerina Project Path github-event-to-email-webhook
-
Click Create.
Choreo creates the Webhook component with the sample implementation and opens the component Overview page.
Step 2: Deploy¶
To deploy the webhook to the development environment, follow these steps:
- In the Choreo Console left navigation menu, click Deploy.
- In the Build Area card, click Configure & Deploy.
-
In the Configurations pane, enter the following information:
-
In the webhookSecret field, enter any value.
Note
Save this value for later use.
-
In the toEmail field, enter the email address to send notification emails.
- Click Deploy.
You can monitor the deployment progress in the Console pane that opens on the right of the page.
-
Once Choreo completes the deployment, the Development card indicates the Deployment Status as Active.
Note
In the deployment card, you can click the icon corresponding to configurables to open the Configurations pane and edit configurations.
Step 3: Connect the webhook to the GitHub repository¶
To allow the webhook to read the labels of issues in a specific GitHub repository, connect the webhook to the GitHub repository:
- In the Choreo Console left navigation menu, click Overview.
- On the Overview page, copy the invoke URL by clicking the copy icon within the URL field.
- Go to your GitHub account and open the repository for which you want to generate notification emails.
- In the top menu, click the Settings tab.
- In the left navigation menu, click Webhooks.
-
Click Add webhook and enter the following information:
Field Value Payload URL The invoke URL you copied in Step 3, sub-step 1. Content Type Select application/json
Secret The last webhook secret you configured in Step 2. Tip
- Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.
- Project Path specifies the location of the project to build the component.
-
Under Which events would you like to trigger this webhook?, select Let me select individual events.
- Select the Issues checkbox in the list of events displayed. This ensures that GitHub issues trigger the webhook.
- Clear the Pushes checkbox to ensure that GitHub does not trigger your webhook when the team pushes changes to the selected GitHub repository.
- Click Add webhook to save the configuration.
Now you have integrated Choreo with GitHub via the webhook you created and deployed. You can proceed to test the webhook.
Step 4: Test¶
To test your webhook, create a GitHub issue with the Bug
label in the repository that you connected to the webhook. You will receive an email similar to the following at the email address you provided in Step 2.
Step 5: Promote¶
To promote the webhook to the Production environment, follow these steps:
- On the Deploy page, go to the Development card and click Promote.
-
In the Configuration Types pane, leave the default selection (i.e., Use default configuration values) unchanged.
Note
If you have configured any default values for the configurable variables, selecting Use default configuration values allows you to proceed with those values. If not, specify values for the configurable variables.
-
Click Next.
-
In the webhookSecret field, enter any value.
Note
Save this value for later use.
-
In the toEmail field, enter the email address to send notification emails.
-
Click Promote.
Once the component is promoted to production, the Production card displays the deployment status as Active.
Now you have successfully created, deployed, and tested a Webhook component and promoted it to production.