Connect n8n to APIs and webhooks with a clear contract

Definitions. An API provides software access to functions or data. A webhook sends a notification to an agreed destination when an event occurs. They are not opposing choices. A workflow can start through a webhook and then call an API to retrieve complete, current information.

Common pattern. A common pattern is: an “order approved” event arrives; n8n checks the sender, reads the order through the source API and writes an authorised result to the destination. The additional read is useful when the event contains only a reference or the underlying information may have changed.

Two nodes. The Webhook node and HTTP Request node serve different roles. Documentation was checked on 26 September 2026. Every actual connection also depends on the target API's contract and permissions.

Contract contents. Specify the event type, required fields, data types, allowed values, schema version and expected response. Identify the delivery ID separately from the business case ID. A notification identifier and an order number may serve different purposes.

This invented payload illustrates a planning contract; it is not a real supplier endpoint:

{
  "event_id": "evt-demo-2048",
  "event_type": "service_request.approved",
  "schema_version": "1",
  "request_id": "REQ-2048",
  "approved_at": "2026-09-26T09:30:00Z"
}

Fields of the example. The event ID supports repeat-delivery detection. The request ID links several events to one business case. The schema version makes changes to the data contract visible. The example deliberately omits full customer information; a targeted read can retrieve necessary data from the authoritative source.

Unknown versions. Document the treatment of unknown versions and event types. An unfamiliar payload should not acquire write authority merely because some field names happen to match. A clear rejection or visible clarification state is preferable to a silent assumption.

Version identification. A new required field or a changed status meaning can break existing senders even when the URL remains unchanged. Agree how a contract version is identified and how long older variants remain supported. For a small internal process, a documented version field may be enough; what matters is unambiguous handling.

Example. In a synthetic example, version 1 supplies a general contact address while version 2 adds a verified billing recipient. An older sender must not be treated as having confirmed the new information. Process it under the previous rule, reject it with a useful reason or request the missing information through the agreed path. Do not invent a substitute.

Reference events. Keep approved representative events for each supported version and check them when either the workflow or sender changes. This exposes differences before real cases reach an incompatible combination.

Two addresses. n8n provides different webhook addresses for testing and production. The test address supports controlled development, while the production address belongs to the published workflow. The Webhook documentation explains their behaviour.

Sender configuration. Configure the sender with the address intended for that environment. Use meaningful names and separate credentials. A successful editor test does not establish that the external application will later call the correct production URL.

Self-hosting. For self-hosting, also check the domain, encrypted transport, reverse proxy and reachability from the actual sender. Test the external route with an authorised request. A local call on the server bypasses the network path that must work in production.

Sender ownership. Record who can change the sender's configuration. A technically ready endpoint is of little use if nobody can update the webhook subscription in the source application during cutover or recovery.

Authentication. A difficult-to-guess address is not a complete authorisation model. Choose authentication supported by the sender and appropriate to the process. n8n documents several webhook authentication methods; provider-specific signature validation must follow and be tested against that provider's protocol.

Signatures. For signed notifications, establish which unmodified data is signed, how timestamps are handled and how key rotation works. Validating a reformatted payload can fail when the provider signs the original bytes. Do not reuse a generic signature recipe without checking the actual contract.

Limits. Restrict permitted events and input sizes. An exposed endpoint should not let arbitrary requests trigger paid models or internal writes. Treat authentication, input validation and business permission as separate checks: a recognised sender can still submit an action that is not allowed.

Authentication mismatch. If the intended sender cannot use the authentication method you first selected, resolve the mismatch explicitly. Removing authentication merely to make the test pass changes the security design and should not become an unnoticed implementation shortcut.

Meaning of the response. Decide what a successful HTTP response means. Does it confirm only that an input was accepted, or that the business process is fully complete? The sending system must understand the same meaning.

Early acknowledgement. For longer processing, an early acknowledgement with later status tracking may be appropriate. It requires reliable capture before acknowledgement. Otherwise, the sender could stop retrying even though the work disappears after a failure.

Synchronous response. For a synchronous response, align maximum processing time, API delays and the sender's timeout. Slow processing can trigger redelivery while the first run is still active. Duplicate protection therefore belongs in the design regardless of the response model.

Unresolved work. Expose unresolved work through a status record or agreed operational view. A sequence of successful acknowledgements can conceal a growing backlog if nobody measures time to the actual business result.

Call parameters. Record the method, URL, authentication, headers, parameters and response format for each outbound call. Use the appropriate managed credential type where it fits. Do not embed production keys in examples or ordinary workflow data fields.

Status and content. Inspect both response status and business content. A technically successful read may return an empty list rather than a valid customer match. Conversely, a setting that routes error responses through normal output must not cause a rejected write to be marked complete.

Pagination. For list requests, account for pagination. A ten-contact test can appear correct while production later reads only the first page of a larger dataset. The HTTP Request documentation describes available controls; the supplier API defines the actual continuation behaviour.

Dates and identifiers. Check dates and identifiers during mapping. Preserve meaningful leading zeros, distinguish absent values from explicit clearing requests, and specify the timezone used for comparisons. These details are part of the interface contract rather than optional cosmetic formatting.

For the invented service_request.approved event above, a design could contain these steps:

1. Authenticate the sender and allow only the intended event type.
2. Validate required fields and schema version.
3. Record the delivery ID through a controlled duplicate-detection mechanism.
4. Read the current request from the source using its request ID.
5. Recheck approval and required business data.
6. Find an existing destination mapping or perform a controlled new action.
7. Store the confirmed destination ID and result state.
8. Expose completion or a visible clarification case.

Why this order. The sequence prevents several common errors. An old notification must not override a subsequently revoked approval. Repeated delivery must not create another order. A missing customer match must not be hidden by selecting the first convenient result.

Evidence. Define the evidence for each transition. “Destination confirmed” should identify the target object, while “awaiting clarification” should identify the missing decision and its owner. This makes later investigation possible without reconstructing every intermediate payload.

Once per business case. Define which action should happen only once for a business case. An order may be created once while later approved changes legitimately update it. Simply ignoring every later event with the same order number would therefore be incorrect.

Idempotency. Use the target API's documented idempotency mechanism where available. A unique processing record may also be necessary. The storage design must handle concurrent access correctly: a simple “search, find nothing, create” sequence can duplicate writes when two executions run simultaneously.

Ordering. Check ordering as well. Yesterday's delayed event must not overwrite a newer confirmed state. A source version or modification timestamp may help when its semantics are reliable. If ordering remains uncertain, read the current state from the authoritative system.

Exactly-once claims. Do not claim exactly-once business behaviour from a single node setting. The result depends on input handling, state storage, target behaviour and recovery together. Demonstrate the relevant cases for the actual architecture.

Failure types. Temporary availability failures may justify bounded retries. Missing permissions or invalid information need a different response. After a timeout that may follow a successful write, reconcile the destination first. Restarting the entire process without checking can duplicate the original effect.

Unresolved cases. Maintain a visible queue of unresolved cases with reference, state, age and next action. An operator should be able to reprocess one corrected case deliberately. The replay must pass the same duplicate and permission checks as the original input.

Missed events. If the sender retries only for a limited period, an additional source-API reconciliation may be required. Establish how missing inputs are detected and which historical interval can be read again. Webhooks alone do not prove that an event can never be lost.

Test these cases for an n8n webhook and API connection:

• a normal case
• unknown sender
• missing field
• duplicate delivery
• concurrent duplicate delivery
• late update
• empty response
• multiple pages

Include lost responses and destination outages.

Expected results. For every test, define the expected state and number of destination actions. Receiving the same approval twice should create one order, rather than two green runs with two orders. An unknown sender must not start paid processing. An unfamiliar schema must not silently trigger guessed mappings.

Evidence for later changes. Retain sanitised inputs and observed results for future changes. They let you recheck the same contract after an API update. Cover representative peaks and file sizes; one successful request is not a load test.

Operating record. Document owners, version, credential renewal, permitted load, response meaning and recovery procedure. Monitor time from receipt to confirmed business outcome as well as HTTP response time. A fast acknowledgement can conceal a growing processing backlog.

Logs and retention. Decide which fields may appear in logs and when retained payloads are removed. Many operating questions need only a case ID, status and timestamp. Copying complete customer documents into every alert rarely improves diagnosis enough to justify the additional access.

Acceptance. The integration is meaningfully accepted when the business team can verify an outcome and the operating team can handle a failure safely. An endpoint address and an API key alone do not constitute a complete integration.

These pages cover the service overview and the related decisions for n8n webhook and API integrations:

• n8n implementation and workflow operations
• n8n retries without duplicate business actions
• Connect n8n to ERP systems with supported interfaces
• CRM automation in n8n without duplicate contacts

For a workflow review, start with the task, systems involved and typical exceptions. Discuss it with modernagents.