Practice

How to Build an Integration Incident Timeline

An incident timeline turns scattered evidence into something you can act on and reuse. What belongs on it, what does not, and how to keep it accurate without a dedicated incident team.

What a timeline is for

Most incident documentation is written to satisfy a process and is never read again. An integration timeline earns its keep differently: integrations fail repeatedly, in the same way, against the same counterparty. The timeline is what makes the second occurrence a ten-minute job instead of a two-day one, and it is the only credible artefact when you need a vendor to accept that a problem is theirs.

What belongs on it

Seven entry types cover almost everything useful:

• First observed occurrence. From raw telemetry, not from the ticket. This is the anchor for everything else.
• Detection. When a human first understood it, and through which channel. The distance from the first entry is your detection gap.
• Scope. Which operations, which records, which customers. Revised as it is understood: keep the revisions rather than overwriting.
• Counterparty contact. Every message to and from the vendor or owning team, with timestamps. This is the part that is almost never captured and almost always needed later.
• Workarounds. Anything applied to mask the symptom, with an explicit note about whether it is still in place.
• Resolution. What actually changed, and on whose side.
• Recurrence links. References to previous timelines with the same signature.

What does not belong

Blame, speculation recorded as fact, and a minute-by-minute transcript of a war room. The test for an entry is whether it would help the next person diagnose a recurrence. Most chat scrollback fails that test.

Keeping it accurate without an incident team

Smaller teams cannot staff a scribe. Three things make timelines survive anyway:

Capture at the source, not afterwards

A timeline assembled from memory a week later is wrong in the details that matter, the timestamps. Entries should be appended as the events happen, which in practice means the timeline has to be built from systems of record rather than written by hand.

Key on the fault, not the ticket

Ticket systems model one report. A recurring integration fault produces a new ticket each time, which is precisely how recurrence gets lost. The timeline needs its own identity that tickets attach to.

Make recurrence explicit

When a new signal matches a previous signature, the system should say so rather than leaving it to whoever happens to remember. This is the difference between MTTR that improves over time and MTTR that resets with every staff change.

Where automation helps

The mechanical parts (watching for matching signatures across monitoring, ticketing and mail, ordering them, noticing that the same signature has appeared three times in a quarter) are the parts humans do badly and inconsistently. The judgement calls, like whether a scope revision is material or whether an escalation is warranted, are the parts humans do well.

That split is the design of Traxivo: the timeline assembles itself from the record your teams already produce, and every outbound message it drafts, including the escalation to the vendor, waits for a named approver before it is sent.

Using the timeline afterwards

Two uses justify the effort. The first is diagnostic: a recurrence is matched to its history immediately. The second is commercial. A timeline showing six occurrences across eight months, with the vendor's own acknowledgements attached, changes a renewal conversation in a way that an engineer's recollection cannot. That is the subject of turning incident history into renewal leverage.

A worked example

What a useful timeline looks like in practice, compressed:

• Day 1, 02:14. First occurrence in telemetry: delivery failures on one endpoint, roughly four percent of calls. No alert, below threshold.
• Day 1, 11:30. An engineer notices retries climbing and ships a workaround that masks the symptom. Error rate returns to zero. Recorded as a mitigation, still in place.
• Day 9. Same signature returns. Because the mitigation is on the record, this is immediately recognised as the same fault rather than a new one.
• Day 9. Scope established: one region, approximately 900 records.
• Day 10. Escalation sent with reproduction, scope and both prior occurrences. Vendor acknowledges a known defect in writing. Reply preserved.
• Day 16. Third occurrence. The acknowledgement from day 10 now carries weight it would not have had alone.
• Day 21. Vendor ships a fix. Verified against our own telemetry, not on their assurance. Backfill run and verified.

The entries that do the work are day 1 at 11:30 and day 10. Without the first, day 9 is a fresh mystery. Without the second, day 16 is an opinion.