Create an Incoming Webhook
Incoming Webhooks are a simple way to integrate external services with your Devopness environments, using a unique URL through which a JSON payload can be sent to run a pipeline with custom input data. Some use cases of external services events include "deploy applications automatically based on GitHub/GitLab/Bitbucket repository updates", "provision and scale infrastructure resources when you payment gateway confirms that a custom subscription has been processed", and many more use cases that can benefit from webhooks integration. Learn how to create an incoming webhook to run pipelines programmatically when events happen on external services.
At Devopness we treat our API-as-a-Product
, meaning that every feature in our product is first designed with the API usage in mind, resulting in an API that is easy to use, well documented and actively maintained and supported.
This API-first
development approach makes it possible that every piece of functionality available to users of our web app can also be automated and integrated with external systems.
Devopness webhooks are a highly performant way to allow applications to push data from external events to trigger pipelines on your infrastructure environments, increasing productivity and reliability while working on cloud applications and infrastructure management workflows.
Webhooks, for now, are an API only feature; so this post will guide you through the usage of our API to help you create a webhook.
Step 1: Get the data needed for creating a webhook
- Take note of the ID (
<pipeline_id>
) of the pipeline which you want to run programaticallyFollow the Deploy Application using an Incoming Hook guide for detailed instructions
- On your local machine, in a terminal window, submit a request to Devopness API endpoint
POST /users/login
using your Devopness account email and passwordcurl --request POST \ --url https://api.devopness.com/users/login \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "email": "<email>", "password": "<password>" }'
- From the previous command response, copy the field
access_token
Step 2: Create the webhook
- On your local machine, in a terminal window, submit a request to Devopness API endpoint
POST /pipelines/:id/hooks/incoming
, replacing<pipeline_id>
.curl --request POST \ --url https://api.devopness.com/pipelines/<pipeline_id>/hooks/incoming \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Deploy `main` branch", "requires_secret": true, "secret_algorithm": "sha256", "secret_header_name": "x-hub-signature-256", "action_type": "deploy", "settings": { "variables": [ { "name": "source_type", "type": "string", "required": false, "default_value": "branch" }, { "name": "source_ref", "path": "pull_request.head.ref", "type": "string", "required": false, "default_value": "main" }, { "name": "pull_request_id", "path": "pull_request.number", "type": "integer", "required": false }, { "name": "pull_request_title", "path": "pull_request.title", "type": "string", "required": false }, { "name": "commit_hash", "path": "pull_request.head.sha", "type": "string", "required": false } ] } }'
Devopness authenticates webhook calls using hash-based message authentication code (HMAC); in summary, a request is considered valid when it provides the header
<secret_header_name>
with the request body encoded using the<secret_algorithm>
and a secret, provided to you by Devopness - From the previous command response, copy the field
url
andsecret
url
is the hook unique URL used to integrate with external services andsecret
is the signature key used to authenticate your webhook calls; this is the only time the secret' value will be returned as text, later operations will mask it
Step 3: Ensure the webhook was created correctly
- On your local machine, in a terminal window, run command to list all the pipeline webhooks, replacing
<pipeline_id>
.curl --request GET \ --url https://api.devopness.com/pipelines/<pipeline_id>/hooks \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json'
- In the previous command response, the recently created hook will be included in the list.
Required Permissions:
NOTE: To complete the steps in this post, the user needs to have the following permissions in the environment:
Resource Type | Permission |
---|---|
Application | View |
Hook | Add |
For instructions on how to grant user permissions in an environment, see Add team to an Environment