Shipmight Logo

Deploy hooks

Trigger a deployment of an app via a HTTP request.

How it works

Deploy hooks are unique URLs which can be used to trigger a new deployment for an app. They can be used in CI flows to automatically release new versions of the app.

Diagram of deployment flow

Triggering a deployment via a deploy hook achieves the same as making a manual deployment via the UI.

Example GitHub workflow

Here's a sample GitHub workflow which implements this flow by pushing an image to GitHub Container Registry and triggering a new deployment:

name: Deploy
  - push
    runs-on: ubuntu-latest
      - uses: actions/checkout@v2
      - name: Store commit ref
        run: echo "SHORT_SHA=`git rev-parse --short HEAD`" >> $GITHUB_ENV
      - name: Build and push image
        run: |
          docker build -t<username>/<imageName>:${{ env.SHORT_SHA }} .
          echo ${{ secrets.GITHUB_TOKEN }} | docker login -u <username> --password-stdin
          docker push<username>/<imageName>:${{ env.SHORT_SHA }}
      - name: Trigger deployment
        run: |
          curl \
            -X POST \
            -H 'Content-Type: application/json' \
            -H 'X-Deploy-Hook-Token: ${{ secrets.DEPLOY_HOOK }}' \
            --data '{"imageTag":"${{ env.SHORT_SHA }}"}' \

Creating deploy hooks

You can find deploy hooks under your application or job settings:

Screenshot of creating a deploy hook

Selecting Create deploy hook opens a modal where you’ll be able to select:

  • Name
    Descriptive name for the hook. Used for presentational purposes only. It’s recommended to include information about where and by whom this hook is used. Cannot be changed later.

After creating the key you’ll be able to copy the unique hook token which is used in the HTTP request URL. This is the only time you can copy this token. If you lose it, you can simply create a new hook and delete the old one.

Deleting a deploy hook invalidates it immediately, so any further requests to it begin failing.

Trigger a deployment via a HTTP request

The endpoint URL is:

POST /api/v1/dh

Request headers must contain the hook token:

X-Deploy-Hook-Token: <deploy-hook-token>

Request body must contain the new image tag to deploy:

  "imageTag": "<tag>"


Example curl request for an application:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Deploy-Hook-Token: <deploy-hook-token>' \
  --data '{"imageTag":"1.2.0"}' \

Example curl request for a job:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Deploy-Hook-Token: <deploy-hook-token>' \
  --data '{"instanceEnvironmentVariables":[{"name":"EXAMPLE_VAR","value":"example"}]}' \

Response status codes

The following status codes are supported:

  • 201 Deployment was triggered successfully
  • 400 Malformed request or validation error
  • 404 Deploy hook was not found
  • 500 Unknown error happened






Join the mailing list to get notified when a new version or new content on the website is released. Max 1 email per week.

Don’t reinvent the shipCopyright © Fine Productions Oy/Ltd