Deploy hooks

Deploy hooks are unique URLs that accept HTTP POST requests to trigger a deployment on an environment.

# Settings

Deploy hooks are configured in the fortrabbit dashboard for each environment.

After enabling a deploy hook, a unique URL is shown. Store it securely and use it to trigger deployments from external services.

# Trigger

To trigger a deployment, send a POST request to the deploy hook URL with a User-Agent header. No authentication or payload is required:

# Trigger
curl -X POST "https://api.fortrabbit.com/webhooks/environments/{{app-env-id}}/deploy/{{SECRET}}" \
  -H "User-Agent: fortrabbit"

Upon successful trigger, the server responds with a deployment object:

{
  "data": {
    "publicId": "dp-abc123"
  }
}

If an error occurs, the response will look like this:

{
  "error": "Environment not found."
}

# Use cases

• Deploy on CMS publish events via webhooks (Contentful, Strapi).
• Scheduled deployments with cron or workflow tools.
• Manual trigger from the CLI with a simple script or alias.
• Automation in GitHub Actions, GitLab CI, or Zapier.

# Example

Triggering a fortrabbit deployment from a GitHub Actions workflow could theoretically work like this:

deploy:
  runs-on: ubuntu-latest
  steps:
    - name: Trigger fortrabbit deploy
      run: |
        curl -X POST "${{ secrets.FORTRABBIT_DEPLOY_HOOK_URL }}" \
          -H "User-Agent: fortrabbit"

NOTE that this is for demonstrational purposes only. Don't take that example literal. GitHub Actions is one kind of integration. Read on for alternatives.

# Alternatives

The deploy hook is a specific solution for specific workflows.

For most day-to-day usage, the GitHub integration with automatic git push to deploy is the most convenient way to deploy.

# Security

Deploy hooks are public! Anyone with the URL can trigger a deployment. Each deploy hook URL contains a unique identifier. Treat this URL with the same security care as you would a password or API token. If you believe your deploy hook URL has been compromised, you can revoke it from the dashboard and create a new one. Consider rotating it on regular basis.

# Troubleshooting

If a deploy hook fails to trigger a deployment:

• Invalid URL: Verify the hook URL is correct and has not been modified
• Revoked hook: Check if the hook was revoked or deleted from the dashboard
• Network issues: Ensure the external service can reach the fortrabbit deployment API
• Check status: View deployment history in the dashboard to confirm if the hook was triggered

You can monitor all deploy hook triggers and their results in the deployment history of your environment.