CircleCI webhook setup
Record build results and link workflow failures to existing Velocity issues.
Set up the callback
- As a Velocity workspace owner or admin, open Settings → Integrations → CircleCI.
- Choose a secret of at least 16 characters and save it in Velocity. Copy the callback URL:
https://velocity.quest/api/webhooks/circleci. - In your CircleCI project settings, open Webhooks and add a webhook with that URL and the same secret. Keep TLS verification enabled and select
workflow-completedandjob-completed. - Save and enable the webhook. Complete a workflow using an issue identifier such as ENG-12 in its branch name or commit subject.
- In Velocity, refresh Recent callbacks. A workflow callback with a matching issue links to it; a failed, canceled or errored workflow adds a build comment. Job callbacks are recorded without adding a duplicate workflow comment.
Authentication and linking
CircleCI signs the raw JSON body with HMAC-SHA256 in circleci-signature: v1=…. Velocity requires a valid signature and selects the workspace using its configured secret. Issue identifiers are matched only within that workspace. CircleCI does not create a new issue automatically.
Change settings
Reload the setup page to see the saved configuration. Generate or replace a secret there, copy it into CircleCI and choose an overlap window while changing it. Disconnecting in Velocity stops accepting that integration’s callbacks; remove or disable the webhook in CircleCI as well.
Troubleshooting
No callback activity means no event has reached Velocity. Check that the project webhook is enabled, the selected events are sent and both secrets match. An unlinked workflow event usually means its branch or commit subject contains no matching issue identifier. A successful CircleCI test ping only checks receipt; run a workflow to check issue linking.