A webhook is a public request boundary. Define method, path, authentication/signature, schema, size, response timing, deduplication, and failure ownership before sharing the URL.

// concept

Separate Test and Production

n8n provides test and production webhook URLs. Test URLs support interactive development; production URLs require an active workflow. Never send a production provider to a temporary test URL.

Use a non-guessable route only as minor defense; it is not authentication. Put TLS and a correctly configured reverse proxy in front of self-hosted n8n. Set the public base/webhook URL according to official documentation.

// concept

Receive Quickly, Process Durably

For providers expecting a fast acknowledgement:

// prompt — copy me2 lines

receive → authenticate → validate envelope → deduplicate event_id
→ persist/queue → acknowledge → process asynchronously

If processing occurs inline, keep timeout bounded and know provider retry behavior. Use Respond to Webhook or node response settings deliberately. Do not return secrets or internal error detail.

Create an endpoint registry containing workflow/version, provider, production path, authentication scheme, event-ID field, response deadline, owner, and disable procedure. Remove old endpoints after provider migration and monitor unexpected calls during a short retirement window. Forgotten active webhook URLs become invisible attack and data-entry paths.

// worked_example

Worked Example

A synthetic form posts {event_id, submitted_at, form_version, payload}. The workflow verifies a shared signature in a trusted pre-processing service or supported mechanism, validates content type/size/schema, and inserts the event ID under uniqueness.

The first delivery returns a controlled accepted response and creates one DRAFT lead task. A provider retry with the same event ID returns accepted/already processed and creates nothing new. Malformed data returns a safe 4xx response and a redacted audit event.

// failure_cases

Failure Cases to Diagnose

6 cases to diagnose

Test URL used in production
activate and register production URL.
Secret URL equals authentication
verify signature/token.
Slow downstream causes provider retry storm
acknowledge after durable receipt.
No unique event
derive/provider ID and deduplicate.
Raw body lost before signature check
preserve exact bytes if scheme requires.
Error response exposes stack
return safe codes.

// pakistan_angle

Pakistan Angle

Payment, courier, wallet, and WhatsApp providers have specific callback contracts. Follow their official signature and inquiry process; never fulfill from query parameters or a browser redirect.

During connectivity problems, queued events should remain durable and customers should see pending status. Avoid retry loops that duplicate orders or messages.

// hands_on

Hands-On Exercise

5 steps

Define the endpoint contract.
build test then production webhook.
validate/authenticate/deduplicate.
test duplicate, malformed, oversized, invalid signature, and downstream outage.
verify one durable effect.

// completion_rubric

Completion Rubric

6 checks — tick as you verify

0/6

// sources

Sources

3 official sources — check every claim yourself

// check_yourself

Check yourself

3 questions · answers and options are taken word-for-word from this course

0/3

1 / 3 · diagnose
Your work shows this failure mode: “Raw body lost before signature check.” What does the lesson tell you to do about it?