Write the integration contract
You will be able to plan an integration that does not create duplicate actions, silent failures, or impossible-to-reconstruct customer records.
Good agent work is useful before it is impressive.
A prompt may decide what to recommend, but integrations move real data and actions. A delayed webhook, duplicate delivery, expired credential, or changed schema can create a customer problem even when the agent’s language is perfect.
Validate, act, record, and recover
The language that keeps the work clear.
How to write the integration contract
Describe the event contract
List source, event name, stable identifier, required fields, authentication, and expected action.
Protect against duplicates
Record the event identifier or state transition before taking a customer-facing action.
Choose safe failure
If validation or a dependent tool fails, hold the case, alert the owner, and preserve enough context to retry.
Log the outcome
Capture when the event arrived, what was validated, what action occurred, and any error or retry.
Worked case: connect apis and webhooks with guardrails
A webinar platform sends a registration event to a client workspace. The workflow validates the event signature, checks a stable registration identifier, creates or updates the contact, and stores the source event ID.
If the event is delivered again, the contact is not enrolled twice in the same sequence. If the contact record cannot be created, the event enters a review queue with the original payload reference and a named owner.
The agent can later use the verified registration context, but the integration itself remains deterministic and auditable.
Complete the working artifact
Assume every external call can fail twice.
A timeout does not tell you whether the remote system did nothing or completed the action and lost the response. Design retries around that ambiguity. Persist workflow state outside the model and give each consequential request an idempotency key or another duplicate-control mechanism.
- Set timeouts and bounded retries with backoff.
- Distinguish safe retry, manual review, compensation, and terminal failure.
- Test a crash after the external action but before local confirmation.
Sources used for this check
Before you move on
- Write the contract for one inbound event.
- Simulate duplicate delivery and missing fields.
- Decide what a human sees when the integration cannot finish.
- The event has a stable identifier.
- Validation precedes customer-facing action.
- Duplicate delivery is harmless.
- Failures remain visible and owned.
Failure drill
A webhook retries after the first request already succeeded
The case
The provider times out before receiving the response. It sends the same event again, so the workflow creates a second contact, books a second appointment, and sends another confirmation.
Your call
- What identity makes the event unique?
- Which step must be safe to repeat?
- Where should a failed partial run resume?
Reveal a defensible response
Response: Verify the sender, store the event ID before side effects, and make each write idempotent. Persist state between steps so a retry can resume or exit cleanly. Return useful errors, cap retries, and send exhausted work to an owned exception queue.
Lesson progress
Finished this lesson?
Save your place on this device so it is easy to pick up where you left off.
Not marked complete yet.