When an integration stops behaving as expected, the first delay can be deciding who owns the problem. The CRM administrator sees the missing update. A developer sees an error. The business team sees a customer process that no longer works.
We recommend writing the response plan before that conversation becomes urgent. A useful runbook connects the technical symptom to a business impact, an authorized responder and a test for recovery.
TLDR: Document what the integration does, who owns each component, how to recognize a failure, what evidence to collect, which actions are authorized and how to verify recovery. Treat retries and replay as controlled changes. Restoring API traffic is only part of the check if business records still need reconciliation.
Start with the integration contract
Describe the source, destination, included objects and fields, update direction and authoritative system for each important value. Identify the schedule or event that triggers the transfer and the expected exception handling.
Add the business process affected by a failure. “Company sync is delayed” is less useful to an incident owner than “the account team cannot see the approved account status needed for its next action.” Keep the technical description, but connect it to a decision someone can make.
Use our overview of HubSpot integrations as inventory context if needed. The runbook must describe the actual connection and configuration your team uses.
Record ownership on both sides
Identify the business owner, the HubSpot administrator, the integration maintainer and the owner of the connected system. Record how each role can be reached and who covers an absence. Avoid assigning all responsibility to the person who first notices the symptom.
Specify who may inspect logs, change configuration, pause processing, rotate credentials or authorize replay. Access and permission to act are separate questions. An incident should not become an excuse to make a consequential change without the required approval.
If a provider is involved, retain the support route and the evidence it needs. Do not put credentials or secret values in the runbook.
Classify the error before choosing the action
HubSpot documents a 403 response when authentication lacks the permissions required for the requested endpoint, and a 429 response when an account or app exceeds an API rate limit. HubSpot's error-handling guide is the primary reference for those responses.
Those codes should guide investigation, not trigger an automatic permission expansion or an endless retry loop.
| Failure class | Evidence to collect | Decision to make |
|---|---|---|
| Authentication or permission | Endpoint, status, sanitized error and recent authorized changes. | Whether the approved access design still matches the operation. |
| Capacity or rate limit | Request pattern, affected operation and applicable limit documentation. | Whether to reduce, queue or reschedule traffic within the approved design. |
| Data or mapping | Affected identifiers, expected values and sanitized validation error. | Whether the source, mapping or business rule needs correction. |
| Transport or service interruption | Timing, affected components and current service evidence. | Whether to wait, contain the impact or escalate to the component owner. |
HubSpot publishes limits that vary by app, account and API context. Its usage guidelines should be checked for the actual endpoint and authentication model. Do not copy a single limit into every runbook.
Collect enough evidence without collecting secrets
Capture the time, affected operation, source and destination identifiers, observed status and a redacted error message. Record the last known successful operation and any approved changes that preceded the issue.
Avoid copying access tokens, authorization headers or complete customer payloads into a general work-management ticket. Define the minimum evidence needed and use the organization's approved location for anything sensitive.
The runbook should tell a responder how to preserve useful evidence before attempting a change. It should also identify when the available evidence is insufficient and the maintainer needs to investigate further.
Separate containment, repair and replay
Hypothetical example: A connection begins returning rate-limit errors while processing an approved backlog. The team confirms the affected operation and asks the authorized maintainer to adjust the request pattern. It does not repeatedly launch the same backlog without checking what already succeeded.
After the correction, the maintainer identifies the failed or unconfirmed items and proposes a bounded replay. Before approval, the team checks whether repeating an operation could create duplicate records, repeat a communication or overwrite a newer value.
This example illustrates the decision sequence. It does not prescribe a retry interval or claim that a particular API operation is safe to repeat. The actual behavior needs to be verified for the endpoint and integration implementation.
For broader troubleshooting context, review common HubSpot issues. Keep any platform-specific diagnostic procedure attached to the runbook rather than burying it in a general task description.
Define recovery in business terms
The recovery test should cover the original failure and any data left incomplete by the interruption. Check representative successful and exceptional cases, then reconcile the affected population according to the integration's purpose.
Record what remains unresolved. If service is restored but historical records still need correction, use separate statuses for those outcomes. Do not close the entire incident solely because the latest request returned successfully.
Use the HubSpot portal audit checklist to identify downstream processes that may need validation. Keep the acceptance criteria specific to the affected integration.
Write an incident note another responder can use
The following fictional incident note is a starting format. It contains no production records, credentials or actual service commitment. Replace the example values with sanitized evidence from your authorized environment.
- Reference: DEMO-SYNC-014, an invented internal incident identifier.
- Business impact: Account status updates from an approved source are not visible to the destination team.
- Observation: The maintainer has recorded rate-limit responses for part of an approved backlog. Successful and unconfirmed items are tracked separately.
- Containment decision: The authorized owner holds the affected replay until the successful population and repeat-operation risks are understood.
- Correction owner: The integration maintainer proposes an adjustment within the verified endpoint limits. The connected-system owner confirms the intended source values.
- Recovery evidence: The approved affected records contain the expected destination values, with unexplained differences still open.
Keep the note factual when the outcome is uncertain. A timeout is not enough evidence to conclude that nothing changed. Before replaying an uncertain operation, inspect the destination using the integration's approved identifiers and check the documented behavior of that operation. The runbook should identify who can make that decision.
Separate actions already authorized from actions needing approval
List the routine read-only checks a responder may perform, such as reviewing a sanitized error and the current configuration reference. List consequential actions separately: changing scopes, rotating a credential, pausing a connection, editing a mapping or replaying a batch. Record the authorizing role and the evidence needed for each decision.
This distinction prevents a vague instruction to “fix sync” from becoming permission to alter the whole integration. If the documented correction no longer matches the observed failure, escalate with the evidence instead of improvising a broader change.
Test the runbook with a safe scenario
We recommend a tabletop exercise before relying on the document during an incident. Give an authorized colleague the fictional note and ask them to identify the affected process, owner, first check, prohibited actions and recovery test. A tabletop exercise does not prove the integration will recover, but it can reveal missing decisions without changing production.
Frequently asked questions
Should every failed request be retried automatically?
No universal retry rule is appropriate. Review the actual endpoint, error and integration behavior. Check whether the earlier operation changed anything and whether repeating it can create an unwanted effect. Use a bounded, authorized correction and verify the result.
Is a successful request enough to close the incident?
We recommend verifying the intended records and business outcome as well as current service operation. Keep any incomplete historical corrections visible even after new traffic succeeds.
Who owns the runbook after launch?
Name an operating owner and a maintainer, with coverage for absences. Review the document when mappings, systems, permissions or responsibilities change. Do not leave ownership implied by whoever last edited it.
Keep the runbook short enough to use
We recommend a clear front page with the purpose, owners, first checks, prohibited actions and escalation route. Link the detailed mapping, test evidence and change history from there. Review it whenever the integration or its ownership changes.
If your team needs help defining that operating responsibility, review HubSpot operations. Bring one real integration and ask whether another authorized person could diagnose, escalate and verify a failure using the documentation alone.
Product documentation checked August 29, 2026. Recheck endpoint behavior and limits before implementing retries, access changes or replay.
