Decent Newsroom
Sign In

Triggering deploys from CI with webhooks and API tokens

By Peon October 28, 2026
How to connect CI pipelines to your deployment platform safely, using webhooks, scoped tokens and watch paths.

Auto deploy on every push is convenient until a broken commit goes straight to production. Most teams want CI to run tests first, then tell the deployment platform to deploy. Webhooks and API tokens make that easy if you set them up carefully.

Three ways to trigger a deploy

  1. Git provider webhook. GitHub or GitLab notifies the platform on push. Simplest, but deploys happen before your tests finish unless the platform waits for status checks.
  2. Deploy webhook from CI. The platform gives each service a secret URL. CI calls it after tests pass.
  3. API call with a token. CI uses a personal or service token to call the platform’s REST API, which allows more control, such as deploying a specific commit or tag.

A minimal CI step

deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - run: curl -fsS -X POST "$DEPLOY_WEBHOOK_URL"
      env:
        DEPLOY_WEBHOOK_URL: ${{ secrets.DEPLOY_WEBHOOK_URL }}

-f makes curl fail on HTTP errors so the CI job turns red if the deploy request is rejected.

Treat webhook URLs as secrets

A deploy webhook URL usually contains a token. Anyone with it can trigger deploys. Store it in CI secrets, never in the repository, and rotate it if it leaks into logs.

Scope API tokens

If you use the API, create a token for CI specifically, not your personal one. Limit it to the projects it deploys, with the lowest role that can deploy. Name it clearly, for example “github-actions-api-prod”, so you know what to revoke.

Watch paths for monorepos

In a monorepo, a change to the docs folder should not redeploy the API. Configure watch paths so a service only redeploys when files under its directory change. This saves build minutes and avoids unnecessary restarts.

Verify signatures on incoming webhooks

If your platform receives webhooks from GitHub or GitLab, make sure it validates the signature header with the shared secret. Unsigned webhooks can be spoofed.

Deploying a specific version

Deploying “whatever is on main” can race with new commits. Prefer deploying a specific commit SHA or image tag that CI just tested. That way what you tested is exactly what ships.

Wait for the result

Fire and forget deploys hide failures. If the platform’s API reports deploy status, have CI poll it and fail the job if the deploy fails. That puts the red X where developers already look.

Notifications

Send deploy results to the team chat channel with the commit, author and link. It doubles as an informal audit trail.

Checklist

  • Tests gate deploys
  • Webhook URLs and tokens in CI secrets
  • CI token scoped and named
  • Watch paths configured for monorepos
  • Deploy a specific SHA or tag
  • CI waits for deploy status

On Peon, the webhooks and automation documentation covers service webhooks for GitHub and GitLab, watch paths and personal API tokens.

Disclosure: I work on Peon.

#ci #webhooks #automation
Write a comment