Bidirectional Sync

Bidirectional sync keeps PagerDuty incidents and Linear issues synchronized in both directions—changes in either system automatically update the other. This ensures your team always has the most current information regardless of which tool they're using.

How Bidirectional Sync Works

Integration Hub maintains synchronization through webhooks in both systems:

• Linear → PagerDuty: Linear webhooks notify Integration Hub when issues change
• PagerDuty → Linear: PagerDuty webhooks notify Integration Hub when incidents change

PagerDuty to Linear Sync

When you take action in PagerDuty, Integration Hub automatically updates the corresponding Linear issue.

Automatic PagerDuty Webhooks

When you create a rule in Integration Hub, a PagerDuty webhook is automatically created for the selected service. You don't need to manually configure anything in PagerDuty—Integration Hub handles this for you.

Status Updates

Example: Acknowledging incident moves Linear issue to "In Progress"

Comment Synchronization

Notes added to PagerDuty incidents are automatically synced as comments on the corresponding Linear issue:

• Add a note in PagerDuty → Comment appears in Linear
• The comment includes the author's name from PagerDuty
• Timestamps are preserved
• Markdown formatting is preserved where possible

Example: PagerDuty note appears as Linear comment

Linear to PagerDuty Sync

Changes in Linear also update PagerDuty incidents automatically.

Status Type: Completed and Canceled

When a Linear issue is moved to a status with type "Completed" or "Canceled", the corresponding PagerDuty incident is automatically resolved.

Example: Marking Linear issue as "Done" resolves PagerDuty incident

Understanding Linear Status Types

Linear organizes workflow statuses into types. Here's how they map:

Sync Timing and Reliability

Real-Time Updates

Both systems use webhooks for near-real-time synchronization:

• Typical Latency: 1-5 seconds from action to sync
• Webhook Delivery: Both Linear and PagerDuty retry failed webhook deliveries
• Processing Time: Integration Hub processes webhooks immediately upon receipt

Conflict Resolution

Integration Hub handles simultaneous changes in both systems:

• Last Update Wins: If changes happen simultaneously, the most recent change takes precedence
• No Sync Loops: Integration Hub tracks which updates it made to prevent infinite sync loops
• Manual Override: Users can manually change status in either system at any time

What Gets Synced vs. What Doesn't

Synced Data

Not Synced

The following data does NOT sync between systems:

• Priority Changes - Changing issue priority in Linear doesn't update incident urgency
• Assignments - Assigning responders in PagerDuty doesn't assign users in Linear
• Linear Comments → PagerDuty - Comments added in Linear don't sync to PagerDuty notes
• Incident Escalations - Escalation actions in PagerDuty don't affect Linear
• Custom Fields - Custom fields in either system are not synced

Sync Flow Examples

Example 1: Complete Incident Lifecycle

1. Engineer creates urgent bug in Linear
   • Linear webhook fires
   • Integration Hub evaluates rules
   • Rule matches (Urgent priority, Triage status)
2. Integration Hub creates PagerDuty incident
   • High-urgency incident created
   • On-call responder paged
   • Incident includes link to Linear issue
3. On-call responder acknowledges incident in PagerDuty
   • PagerDuty webhook fires
   • Integration Hub updates Linear issue
   • Linear issue moves to "In Progress" status
4. Responder adds notes in PagerDuty
   • Each note syncs as a comment in Linear
   • Team sees investigation progress
5. Responder resolves incident in PagerDuty
   • PagerDuty webhook fires
   • Integration Hub updates Linear issue
   • Linear issue moves to "Done" status

Diagram: Complete incident lifecycle with bidirectional sync

Example 2: Linear-First Resolution

1. Bug reported in Linear, incident created in PagerDuty
   • Engineer on-call gets paged
2. Engineer acknowledges incident in PagerDuty
   • Linear issue moves to "In Progress"
3. Engineer fixes bug and marks Linear issue as "Done"
   • Linear webhook fires (status changed to Completed type)
   • Integration Hub resolves PagerDuty incident automatically

Monitoring Sync Health

Webhook Status

Check webhook health regularly:

• Linear Webhooks: View in Integration Hub Webhooks tab
• PagerDuty Webhooks: Automatically managed per service
• Status Indicators: Look for "Active" status on all webhooks

Sync Verification

To verify sync is working:

1. Create a test issue in Linear that matches your rule criteria
2. Verify incident is created in PagerDuty
3. Acknowledge the incident in PagerDuty
4. Check that Linear issue status updated
5. Add a note in PagerDuty
6. Check that comment appears in Linear
7. Mark Linear issue as "Done"
8. Verify PagerDuty incident is resolved

Troubleshooting Bidirectional Sync

Status Updates Not Syncing from PagerDuty

Problem: Acknowledging/resolving in PagerDuty doesn't update Linear

Solution:

• Check that the PagerDuty webhook exists for the service (go to Service → Integrations in PagerDuty)
• Verify Linear connection is active
• Confirm the rule has acknowledged/resolved status mappings configured
• Check that the Linear issue still exists and isn't archived
• Verify you have permission to update issues in Linear

Comments Not Syncing

Problem: PagerDuty notes aren't appearing as Linear comments

Solution:

• Verify Linear connection is active
• Check that the PagerDuty webhook is active for the service
• Ensure you have permission to comment on Linear issues
• Try adding a new note to see if recent notes sync

Linear "Done" Not Resolving Incident

Problem: Marking Linear issue as done doesn't resolve PagerDuty incident

Solution:

• Verify the status type is "Completed" or "Canceled" (check in Linear Settings → Workflow States)
• Confirm the Linear webhook is active
• Check that PagerDuty connection is active
• Ensure the incident still exists and isn't already resolved

Sync Delays

Problem: Sync takes longer than expected

Solution:

• Normal latency is 1-5 seconds; occasional delays up to 30 seconds are normal
• Check PagerDuty and Linear status pages for service issues
• High volume of events may cause temporary delays
• If delays persist beyond 1 minute, check webhook health

Best Practices

Status Mapping Strategy

• Acknowledged Status: Map to an active work status (e.g., "In Progress," "In Review")
• Resolved Status: Map to a terminal status (e.g., "Done," "Resolved")
• Consistency: Use the same status mappings across similar rules for predictability

Communication

• Educate your team that changes in PagerDuty will update Linear automatically
• Encourage on-call responders to add detailed notes in PagerDuty for team visibility
• Document your team's workflow so everyone understands which statuses trigger what actions

Testing

• Test bidirectional sync thoroughly before relying on it for production incidents
• Create test issues and incidents to verify sync works as expected
• Verify sync works for all configured status mappings

Next Steps

• Review Best Practices →
• Troubleshooting Guide →
• Learn More About Rules →