CI/CD
Deploy Hooks
Deploy hooks let you trigger a deployment from any external system, CircleCI, Jenkins, a shell script, or anything that can make an HTTP POST request. Each hook is a unique HTTPS URL that acts as both the endpoint and the authentication token.
You can create multiple hooks per service, one per CI provider, one per branch, or one per environment. Each hook can be scoped to deploy a specific branch, giving you fine-grained control over what gets deployed and when.
Triggering a deploy
# Trigger a deploy, no body or auth headers needed
curl -X POST "https://api.stackblaze.cloud/v1/hooks/sh_live_abc123xyz789"
# Response
{
"status": "queued",
"deployment_id": "dep_9f3k2m...",
"message": "Deploy queued successfully"
}
# HTTP Status: 202 Accepted
GitHub Actions example
name: Deploy to StackBlaze
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Run tests
run: npm test
- name: Deploy to StackBlaze
run: |
curl -X POST "$${ secrets.STACKBLAZE_DEPLOY_HOOK }"
env:
STACKBLAZE_DEPLOY_HOOK: $${ secrets.STACKBLAZE_DEPLOY_HOOK }
Common use cases
CircleCI
Trigger a StackBlaze deploy at the end of a successful CircleCI pipeline using a curl step.
Jenkins
Add a post-build action in your Jenkinsfile to POST to the hook URL after tests pass.
Custom scripts
Call the hook from any shell script, Makefile target, or deployment automation.
Zapier / n8n
Wire up a Zapier webhook action or n8n HTTP Request node to deploy on any trigger.
GitHub Actions
Use a curl step in a GitHub Actions workflow for fine-grained deploy control beyond auto-deploy.
Scheduled deploys
Combine with a cron job (e.g. cron.org) to deploy your service on a schedule, refreshing data or config.
Rate limit
Deploy hooks are rate-limited to 10 deploys per minute per service. Requests exceeding this limit return 429 Too Many Requests. Build a back-off into any automation that may trigger rapid successive deploys.
Under the hood
- Cryptographic token: the hook URL contains a 256-bit random token generated with a CSPRNG at creation time. Tokens are stored as bcrypt hashes in the database. Revoke a hook at any time from the Settings page, this immediately invalidates the URL.
- Asynchronous queueing: the 202 Accepted response is returned before the build starts. The deploy is added to the service's build queue. If a build is already running, the hook deploy waits in line and starts when the current build completes.
- Branch scoping: per-branch hooks clone and build the specified branch. If no branch is set on the hook, the service's configured trigger branch is used. This lets you create separate production and staging hooks on the same service.
Step by step
Generate a deploy hook
Navigate to Dashboard → Service → Settings → Deploy Hooks → Create Hook. Give it a descriptive name (e.g. "CircleCI deploy") and optionally select a specific branch. StackBlaze generates a unique HTTPS URL containing a cryptographic token.
Store the URL as a secret
The hook URL itself is the authentication credential, anyone with the URL can trigger a deploy. Store it as an encrypted secret in your CI system (CircleCI environment variable, GitHub Actions secret, etc.) and never commit it to version control.
POST to the hook URL
Send an HTTP POST request to the hook URL from your external system. No request body or authentication headers are required, the URL token is sufficient. StackBlaze responds immediately with 202 Accepted and queues the deploy asynchronously.
Monitor the deploy
Check the Deployments tab in the StackBlaze dashboard to see the triggered deploy. You can also poll the GET /services/{id}/deployments API endpoint to programmatically wait for completion and check the status field.