OpsTrailsDocs
Console

Webhooks

Receive events automatically from your Git platform via webhooks. OpsTrails supports GitHub, GitLab, and Bitbucket webhooks out of the box.

📝 Note

First, open Ingestion → Webhooks in the console and click Generate to create your webhook secret. It is stored encrypted and shown only once, so copy it before leaving the page. Replace YOUR_ORG_ID with your organization ID and YOUR_WEBHOOK_SECRET with that value below.

📝 Note

For GitHub and GitLab the secret goes only in the platform's own secret field — never in the URL — so it is never exposed in request logs or referrers. OpsTrails verifies each request against the secret it has stored for your organization.

GitHub

Go to your repository's Settings → Webhooks → Add webhook and configure. Put your secret in GitHub's Secret field — GitHub signs each request with HMAC-SHA256 and OpsTrails verifies the signature:

Payload URL: https://api.opstrails.dev/api/v1/webhooks/github?org=YOUR_ORG_ID
Content type: application/json
Secret: YOUR_WEBHOOK_SECRET
Events: deployment, deployment_status

GitLab

Go to your project's Settings → Webhooks and configure. Put your secret in GitLab's Secret token field — GitLab sends it as the X-Gitlab-Token header, which OpsTrails verifies:

URL: https://api.opstrails.dev/api/v1/webhooks/gitlab?org=YOUR_ORG_ID
Trigger: Deployment events
Secret token: YOUR_WEBHOOK_SECRET

Bitbucket

Bitbucket Cloud doesn't support signed webhooks or a secret header, so the secret stays in the URL — OpsTrails still verifies it against your stored secret rather than accepting any value. Go to your repository's Settings → Webhooks → Add webhook and configure:

URL: https://api.opstrails.dev/api/v1/webhooks/bitbucket?org=YOUR_ORG_ID&secret=YOUR_WEBHOOK_SECRET
Events: repo:commit_status_created, repo:commit_status_updated

Which events are recorded

OpsTrails only creates timeline entries for deployment-type events:

📝 Note

Sending all events is safe — any other event (push, pull request, the initial ping, etc.) is signature-verified and then ignored, so it won't appear on your timeline. If you enabled a webhook and see nothing, it's almost certainly working; trigger an actual deployment to see an entry. Check your platform's Recent Deliveries — a 200response means OpsTrails accepted (and, for non-deployment events, safely ignored) the request; a 401 means the secret doesn't match the one stored in the console.
Previous← JenkinsNextOpenTelemetry →