Notify Shipyrd via HTTP (cURL)

Notify Shipyrd from any language or CI pipeline with a single HTTP POST. No gem, no SDK — just one HTTP request.

What it does

Each deploy POSTs a small JSON payload to https://hooks.shipyrd.io/deploys.json. Shipyrd records the event, updates the dashboard, fires any configured notifications, and unlocks the destination if applicable.

Setup

  1. Get your deploy token from Shipyrd: open the application and go to its Setup page. Copy the token.

  2. Make it available to your script as an environment variable. In CI, set it as a secret named SHIPYRD_API_KEY.

  3. POST when your deploy starts and again when it finishes:

    # Pre-deploy
curl -X POST https://hooks.shipyrd.io/deploys.json \
  -H "Authorization: Bearer $SHIPYRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploy": {
      "status": "pre-deploy",
      "performer": "you@example.com",
      "version": "abc1234",
      "destination": "production",
      "command": "deploy"
    }
  }'

    # Post-deploy (on success)
curl -X POST https://hooks.shipyrd.io/deploys.json \
  -H "Authorization: Bearer $SHIPYRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploy": {
      "status": "post-deploy",
      "performer": "you@example.com",
      "version": "abc1234",
      "destination": "production",
      "command": "deploy"
    }
  }'

    On failure, send the same payload with "status": "failed" so the dashboard doesn’t show the deploy stuck in pre-deploy.

  4. Wire those calls into the start, success, and failure paths of your deploy step.

Payload fields

The deploy object accepts:

Field Required Description
status yes One of pre-deploy, post-deploy, failed
performer yes Who’s deploying — a GitHub profile URL or an email matching a Shipyrd user
version yes The git SHA or release tag being deployed
destination yes Environment name, e.g. production, staging
command no The deploy command, typically deploy
commit_message no First line of the commit message
service_version no Service@version string when one application has multiple services
recorded_at no ISO 8601 timestamp; defaults to now

The application is identified by the API token — there’s no app field in the payload.

Verify it worked

A successful POST returns HTTP 201. Open Shipyrd and check the timeline for the application; the deploy should appear with the matching version and destination, attributed to the performer you sent.