Webhooks
Webhooks: secret deploy hook URLs and GitHub push events. They authenticate with their own secrets, never the API token.
/hooks/deploy/{service_id}Same as POST, for tools that can only send GET requests.
Path Parameters
The service's id (names are not accepted: they are guessable).
Query Parameters
The service's deploy hook key (part of its deploy_hook_path).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/hooks/deploy/string"{ "commit_message": "string", "commit_sha": "string", "created_at": "2019-08-24T14:15:22Z", "error": "string", "finished_at": "2019-08-24T14:15:22Z", "id": "string", "image": "string", "port": 0, "service_id": "string", "source": { "branch": "string", "commit": "string", "kind": "git", "repo_url": "string" }, "started_at": "2019-08-24T14:15:22Z", "status": "queued", "trigger": "create"}/hooks/deploy/{service_id}Queues a deploy of the service's configured source. The URL (deploy_hook_path of the service) is the secret: no token needed. Rotate it with POST /api/v1/services/{id}/deploy-hook/rotate.
Path Parameters
The service's id (names are not accepted: they are guessable).
Query Parameters
The service's deploy hook key (part of its deploy_hook_path).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/hooks/deploy/string"{ "commit_message": "string", "commit_sha": "string", "created_at": "2019-08-24T14:15:22Z", "error": "string", "finished_at": "2019-08-24T14:15:22Z", "id": "string", "image": "string", "port": 0, "service_id": "string", "source": { "branch": "string", "commit": "string", "kind": "git", "repo_url": "string" }, "started_at": "2019-08-24T14:15:22Z", "status": "queued", "trigger": "create"}/hooks/githubSet it up in GitHub with the server's webhook secret (github_webhook_secret). A push deploys (trigger webhook, commit = after) every auto-deploy service whose repository and branch match; ping answers {"ok": true}; other events are ignored. Replayed deliveries (same body or delivery id) are ignored too.
Header Parameters
sha256=<hex HMAC-SHA256 of the raw body> with the webhook secret.
push, ping, ...
Delivery id (used to ignore redeliveries).
The event payload: JSON, or form-encoded with the JSON in a payload field (GitHub's default content type). At most 25 MiB.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/hooks/github" \ -H "X-Hub-Signature-256: string" \ -H "X-GitHub-Event: string" \ -H "Content-Type: application/json" \ -d '{}'{ "deploys": [ { "commit_message": "string", "commit_sha": "string", "created_at": "2019-08-24T14:15:22Z", "error": "string", "finished_at": "2019-08-24T14:15:22Z", "id": "string", "image": "string", "port": 0, "service_id": "string", "source": { "branch": "string", "commit": "string", "kind": "git", "repo_url": "string" }, "started_at": "2019-08-24T14:15:22Z", "status": "queued", "trigger": "create" } ], "ignored": true, "ok": true, "reason": "string"}