PagerDuty Integration

Bring incidents into Velocity, keep their status in sync, and see who is on call.

Connect PagerDuty

1. As a workspace admin or owner, open Settings → Integrations → PagerDuty.
2. Click Connect PagerDuty and authorize your PagerDuty account. Velocity keeps the access and refresh tokens on the server.
3. For each service to import, select a Velocity team and, optionally, a project. Select the team statuses to use for triggered, acknowledged, and resolved incidents.
4. Review the synchronization options and click Save changes.
5. Click Register service webhooks. Velocity creates a signed webhook subscription for each mapped service. Re-register after adding or removing service mappings.

A connection alone does not subscribe your services to incident events. Service mappings and webhook registration are required before new incidents can arrive. Existing incident history is not imported when you connect.

Reconnecting to a different PagerDuty account, or an account whose identity cannot be confirmed as the previous one, clears service and responder mappings and stops trusting the old webhook subscriptions. Map the new account's services and register their webhooks again. Remove the old Velocity webhook subscriptions in the previous PagerDuty account too.

Incident routing and priority

Triggered incidents create issues in the service's selected team when Create issues from triggered incidents is enabled. An optional project keeps those issues with the related work. The issue links to the PagerDuty incident; subsequent events update that linked issue instead of creating another issue for every status change. A note on the incident links back to its new Velocity issue.

You can change either priority in the PagerDuty settings page.

With Automatic status, a new issue starts in the team's default status. Later incident updates use the first unstarted, started, or completed status for triggered, acknowledged, or resolved incidents respectively. Select explicit statuses to override this.

Choose what to synchronize

Issue creation starts enabled for new connections. The options below start disabled and can be enabled independently. Changes apply to linked incidents in this workspace.

• Update Velocity status from PagerDuty: incident status changes update the issue using the service's status mapping. Resolving an incident keeps the Velocity issue and its history.
• Update PagerDuty status from Velocity: moving a linked issue to an active or completed status acknowledges or resolves the incident. Enable this only when you want issue edits to change PagerDuty incidents. Reopening an issue does not reopen a PagerDuty incident.
• Import incident notes as comments: copy notes from a PagerDuty incident into its linked Velocity issue's discussion.
• Show who is on call: show current responders and escalation levels alongside PagerDuty references in issue details. Workspace members can see this context when enabled.

Optionally map PagerDuty responders to Velocity members for issue assignment. A matching member must belong to this workspace. No member mapping is required to connect.

Webhook security

PagerDuty generates a signing secret for each service subscription. Velocity stores those secrets on the server and verifies the X-PagerDuty-Signature header against the raw request body before processing an event. The settings page never displays these secrets.

Webhook registration requires a publicly reachable HTTPS deployment. A local test or passing automated test does not prove PagerDuty can deliver events to your deployment.

Disconnect

Disconnecting removes Velocity's stored credentials and settings and stops accepting incident events. Existing links on issues stay. Remove the service webhook subscriptions and revoke Velocity's authorization in PagerDuty as well; revoking an account authorization can also affect other Velocity workspaces connected with that account.

Server setup

For operators hosting Velocity, register a PagerDuty OAuth app with the redirect URI https://YOUR_VELOCITY_HOST/api/auth/pagerduty/callback. Configure PAGERDUTY_CLIENT_ID and PAGERDUTY_CLIENT_SECRET on the web deployment. The app uses scoped OAuth with PKCE and these permissions:

This integration currently uses PagerDuty's US-region OAuth and API endpoints. EU-region accounts are not supported.

incidents.read incidents.write services.read users.read oncalls.read
webhook_subscriptions.read webhook_subscriptions.write

See PagerDuty's OAuth documentation and webhook signature documentation for the provider requirements. A registered app, configured deployment, and authorized PagerDuty account are required for live use.

Troubleshooting

• The server is not configured: ask the Velocity operator to configure the OAuth app credentials, then connect again.
• No incidents arrive: confirm the service has a team mapping, save it, register service webhooks, and trigger a new incident. Check the deployed webhook is reachable.
• Authorization expired: reconnect from the settings page. Refresh tokens cannot extend authorization indefinitely.
• Account identity could not be verified: reconnect PagerDuty to verify the account before loading services, registering webhooks, or showing on-call responders.
• No on-call responders appear: enable the on-call option and confirm the mapped service has an escalation policy with a current responder in PagerDuty.
• Status does not update: enable the appropriate direction and check the mapped statuses belong to the selected team. Outbound updates need a valid authorizing PagerDuty user.