Property management integration retry runbook

Updated July 2026

Define the smallest external effect: create one vendor work order for an approved scope, send one appointment confirmation, initiate one authorized payment, or post one provider-returned payment event. “Handle maintenance” or “sync payments” is too broad because it hides several actions with different recipients, authority, reversibility, and receipts.

Give that effect a durable business-action identity derived from stable source context, not a random value generated for each request. Record the property, source object and version, recipient or payee, amount or scope, effective policy, approval if required, and current workflow state. If those facts change, decide whether the old action should be cancelled and a new one reviewed.

Many queues and webhooks provide at-least-once delivery. Redelivery is not necessarily a provider defect; it is a reliability strategy that expects the consumer to recognize prior work. Store the source event ID and consumption result durably so a worker restart, deployment, or concurrent delivery cannot open another internal action for the same event.

Deduplication needs scope and retention. An event ID may be unique only inside one provider account or event type, and a late redelivery can arrive after a short cache expires. Document the uniqueness boundary and retain the consumption record long enough for the provider’s delivery behavior and the business consequence.

A provider-supported idempotency key lets repeated requests for the same action return or preserve one result instead of creating another effect. Reuse the same key on every retry. Confirm which endpoints support it, how request-body differences are handled, how long keys are retained, whether failures are cached, and whether the guarantee applies across regions or accounts.

A local “already sent” flag is useful but incomplete. The process can fail after the provider accepts the request and before the local flag is committed. That gap is exactly where a stable provider identity matters. Conversely, provider idempotency does not replace local event deduplication; duplicate source events can still create separate action identities unless the internal boundary is controlled.

A definitive validation rejection can be corrected without assuming an external effect exists. A processing response says wait or query. A completed response says reconcile and stop. A timeout, broken connection, or worker crash after the call creates an unknown state. Treating unknown as failed is the classic blind-retry error.

Define allowed transitions. For example, proposed may become approved, requested, accepted, processing, completed, rejected, cancelled, unknown, or exception. Require evidence for each transition and disallow impossible reversals. Late provider events should not push a completed or cancelled action backward without review.

Use the existing idempotency identity, provider request ID, or supported search fields to query the outcome. If one external record exists, link its receipt and reconcile the internal workflow. If the provider conclusively reports no accepted action and the authority remains valid, the same action may be retried under the documented policy. If the provider cannot resolve the state, stop and route it to a person.

Manual recovery must be specific. The reviewer should see the source event, intended effect, each attempt, timestamps, response or timeout, provider lookup, current external candidates, authority, and safe next actions. “Retry?” is not enough context for a payment, resident message, or vendor dispatch.

For a small landlord, the recovery path can remain compact without becoming informal. Keep one action timeline that shows the internal proposal, approval boundary, provider attempts, bank or delivery evidence where applicable, and final source-record update. If correction requires cancelling a duplicate work order, reversing a ledger entry, or contacting a provider, record the compensating step under a new authorized action linked to the original rather than rewriting history.

Use sandbox or inert recipients and synthetic records. Deliver the same event twice, start two consumers concurrently, drop the provider response after acceptance, restart the worker between call and local commit, delay a success event past the timeout, and deliver processing and completed events out of order. Verify that one intended action produces at most one external effect.

Test cancellation and changed facts too. Approve an action, change the lease, vendor, amount, access instruction, or recipient before execution, and confirm the policy rechecks volatile facts. A stable idempotency key prevents duplicates; it does not prove that a stale action remains appropriate.

A technically retry-safe action can still be outside policy. A payment may exceed an amount cap, a message may have legal effect, a vendor dispatch may reveal access information, or a resident-account change may be disputed. Apply the action-authority boundary before the retry logic and recheck it when facts or time-sensitive consent can change.

AI can classify a technical failure, gather receipts, compare state, and draft a recovery packet. It should not invent missing authority or resolve consequential ambiguity merely because the API supports a retry. The safest automation is often a precise abstention that preserves state and gives a reviewer the evidence needed for one decision.

It is a repeated attempt for the same still-authorized business action using the same provider-supported idempotency identity, after duplicate event delivery and existing provider outcome have been checked. The result is reconciled to one internal action record.

Mark the action outcome unknown, preserve the attempt, and query or reconcile provider state using the existing identity. Do not assume failure or generate a new action key. If state remains uncertain, route a complete packet to an authorized reviewer.

Any external or financial effect benefits, including payments, owner disbursements, resident messages, notices, e-signature envelopes, vendor dispatches, work-order creation, listing publication, ledger posts, and document generation tied to a real workflow.

No. Idempotency addresses duplicate effects for a defined action. The agent still needs current source evidence, explicit authority, privacy and permission controls, human-required categories, cancellation behavior, provider receipts, exception ownership, and review of consequential decisions.