28 ਅਕਤੂ 2025·4 ਮਿੰਟ

ਭਰੋਸੇਯੋਗ webhook ਇੰਟੀਗ੍ਰੇਸ਼ਨ: ਦਸਤਖ਼ਤ, idempotency, ਡੀਬੱਗਿੰਗ

Q: Why do webhooks seem to “randomly” fail or duplicate in production?

Because webhook delivery is usually at-least-once , not exactly once. Providers retry on timeouts, 5xx responses, and sometimes when they don’t see your 2xx in time, so you can get duplicates, delays, and out-of-order deliveries even when everything is “working.”

Q: What’s the safest basic flow for handling a webhook request?

Default to this rule: verify the signature first, then store/dedupe the event, then respond 2xx, then do heavy work asynchronously . If you do heavy work before replying, you’ll hit timeouts and trigger retries; if you reply before recording anything, you can lose events on crashes.

Q: How do I avoid signature mismatches when verifying webhooks?

Use the raw request body bytes exactly as received. Don’t parse JSON and re-serialize before verification—whitespace, key order, and number formatting changes can break signatures. Also make sure you’re recreating the provider’s signed payload precisely (often ).

Q: What should my endpoint do when signature verification fails?

Return a 4xx (commonly 400 or 401) and do not process the payload. Log a minimal reason (missing signature header, mismatch, bad timestamp window), but don’t log secrets or full sensitive payloads.

Q: What is an idempotency key for webhooks, and which value should I use?

An idempotency key is a stable unique identifier you store so retries don’t re-apply side effects. Best options: - Event ID (ideal when one event maps to one business change) - Delivery/message ID (if it stays constant across retries) - Hash of stable fields (last resort) Enforce it with a unique constraint so only one request wins under concurrency.

Q: How do I dedupe webhooks without race conditions?

Write the idempotency key before doing side effects, with a uniqueness rule. Then either: - Mark it processed after success, or - Record a failure status so you can retry safely If the insert fails because the key already exists, return 2xx and skip the business action.

Q: How do I add replay protection without rejecting legitimate retries?

Use a timestamp in the signed data and reject requests outside a short window (for example, a few minutes). To avoid blocking legitimate retries: - Allow some clock drift - Log your server time and received timestamp on rejection - Treat idempotency as the main protection against duplicates; the time window is mainly to stop late replays

Q: How should I handle out-of-order webhook events?

Don’t assume delivery order equals event order. Make handlers tolerant: - Use upserts where possible - Check current state before applying changes - If an object isn’t found, consider retrying later (via a queue) instead of permanently failing Store the event ID and type so you can reason about what happened even when order is weird.

Q: What should I log so webhook debugging doesn’t turn into guessing?

Log a small “receipt” per delivery attempt so you can trace one event end-to-end: - provider, event id, delivery id - signature ok, replay ok - idempotency result (new/duplicate) - response code, latency ms - timestamps (received/first seen/last seen) Keep logs searchable by event ID so support can answer customer reports quickly.

Q: What’s a fast way to investigate a customer report that “a webhook never arrived”?

Start by asking for a single concrete identifier: event ID or delivery ID , plus an approximate timestamp. Then check in this order: 1. Signature verification result 2. Timestamp/replay window result (if used) 3. Idempotency outcome (new vs duplicate) 4. What you returned (status code + latency) If you build endpoints using Koder.ai, keep the handler pattern consistent across projects (verify → record/dedupe → queue → respond). Consistency makes these checks fast when incidents happen.

ਸਿੱਖੋ ਕਿ ਕਿਸ ਤਰ੍ਹਾਂ webhook ਨੂੰ ਭਰੋਸੇਯੋਗ ਬਣਾਇਆ ਜਾਵੇ — ਦਸਤਖ਼ਤ ਵੇਰੀਫਿਕੇਸ਼ਨ, idempotency keys, replay ਪ੍ਰੋਟੈਕਸ਼ਨ, ਅਤੇ ਗਾਹਕ-ਰਿਪੋਰਟ ਕੀਤੀਆਂ ਫੇਲੀਆਂ ਦੀ ਤੇਜ਼ ਡੀਬੱਗਿੰਗ ਵਰਕਫਲੋ।

ਅਸਲ ਜ਼ਿੰਦਗੀ ਵਿੱਚ webhooks ਕਿਉਂ fail ਕਰਦੇ ਹਨ

ਜਦੋਂ ਕੋਈ ਕਹਿੰਦਾ ਹੈ “webhooks ਕੇ ਟੁੱਟ ਗਏ ਹਨ,” ਓਹ ਆਮ ਤੌਰ 'ਤੇ ਤਿੰਨ ਗੱਲਾਂ ਵਿੱਚੋਂ ਇੱਕ ਦਾ ਮਤਲਬ ਹੁੰਦਾ ਹੈ: ਇਵੈਂਟ ਆਏ ਹੀ ਨਹੀਂ, ਇਵੈਂਟ ਦੋ ਵਾਰੀ ਆਏ, ਜਾਂ ਇਵੈਂਟ ਇਕ ਉਲਝਣ ਭਰੇ ਕ੍ਰਮ ਵਿੱਚ ਆਏ। ਗਾਹਕ ਦੀ ਨਜ਼ਰ ਵਿੱਚ ਸਿਸਟਮ ਨੇ ਕੁਝ "ਮਿਸ" ਕੀਤਾ। ਤੁਹਾਡੇ ਨਜ਼ਰੀਏ ਤੋਂ, ਪ੍ਰੋਵਾਈਡਰ ਨੇ ਇਹ ਭੇਜ਼ਿਆ ਪਰ ਤੁਹਾਡੀ ਐਂਡਪੌਇੰਟ ਨੇ ਉਸਨੂੰ ਕਬੂਲ ਨਹੀਂ ਕੀਤਾ, ਪ੍ਰੋਸੈਸ ਨਹੀਂ ਕੀਤਾ, ਜਾਂ ਉਮੀਦ ਮੁਤਾਬਿਕ ਰਿਕਾਰਡ ਨਹੀਂ ਕੀਤਾ।

Webhooks ਇੰਟਰਨੈੱਟ ਉੱਤੇ ਜੀਵਨ ਯਾਪਨ ਕਰਦੇ ਹਨ। ਰਿਕਵੇਸਟ ਡੀਲੇ ਹੋ ਜਾਂਦੀਆਂ ਹਨ, ਰੀਟ੍ਰਾਈ ਹੁੰਦੇ ਹਨ, ਅਤੇ ਕਦੇ-ਕਦੇ ਗਲਤ آرਡਰ ਵਿੱਚ ਡਿਲਿਵਰ ਹੋ ਜਾਂਦੀਆਂ ਹਨ। ਜ਼ਿਆਦਾਤਰ ਪ੍ਰੋਵਾਈਡਰ ਟਾਈਮਆਊਟ ਜਾਂ ਨਾਨ-2xx ਜਵਾਬ ਵੇਖ ਕੇ ਜ਼ੋਰ ਨਾਲ ਰੀਟ੍ਰਾਈ ਕਰਦੇ ਹਨ। ਇਹ ਇਕ ਛੋਟੀ ਸਮੱਸਿਆ (ਹੌਲੀ ਡੇਟਾਬੇਸ, ਡਿਪਲੋਏ, ਛੋਟਾ ਆਊਟੇਜ) ਨੂੰ ਡੁਪਲਿਕੇਟਸ ਅਤੇ ਰੇਸ ਕਨਡੀਸ਼ਨਾਂ ਵਿੱਚ ਬਦਲ ਦੇਂਦਾ ਹੈ।

ਖਰਾਬ ਲੌਗ ਇਸਨੂੰ ਬੇਤਰਤੀਬੀ ਜਿਹਾ ਮਹਿਸੂਸ ਕਰਵਾਉਂਦੇ ਹਨ। ਜੇ ਤੁਸੀਂ ਇਹ ਸਾਬਤ ਨਹੀਂ ਕਰ ਸਕਦੇ ਕਿ ਰਿਕਵੇਸਟ ਅਦਾ ਹੁੰਦੀ ਸੀ, ਤਾਂ ਤੁਸੀਂ ਉਸ 'ਤੇ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਕਾਰਵਾਈ ਨਹੀਂ ਕਰ ਸਕਦੇ। ਜੇ ਗਾਹਕ ਦੀ ਸ਼ਿਕਾਇਤ ਨੂੰ ਕਿਸੇ ਖਾਸ ਡਿਲਿਵਰੀ ਅਟੈਮਪਟ ਨਾਲ ਜੋੜ ਨਹੀਂ ਸਕਦੇ, ਤਾਂ ਅਨੁਮਾਨ ਲੱਗਾਉਣਾ ਪੈਂਦਾ ਹੈ।

ਅਸਲ-ਦੁਨੀਆ ਦੀਆਂ ਅਕਸਰ ਫੇਲੀਆਂ ਕੁਝ ਬੱਕੇਟਾਂ ਵਿੱਚ ਆਉਂਦੀਆਂ ਹਨ:

“ਗੁੰਮ” ਹੋਏ ਇਵੈਂਟ (ਤੁਸੀਂ ਟਾਈਮਆਊਟ ਹੋ ਗਏ, ਏਰਰ ਵਾਪਸ ਕੀਤੀ, ਜਾਂ ਐਕਨੌਲੈਜ ਕਰਨ ਤੋਂ ਬਾਅਦ ਫੇਲ ਹੋਏ)
ਡੁਪਲਿਕੇਟਸ (ਰੀਟ੍ਰਾਈਅਾਂ ਤੇ ਹੈਂਡਲਰ ਜੋ idempotent ਨਹੀਂ ਹੈ)
ਗਲਤ ਕ੍ਰਮ (ਤੁਸੀਂ ਮੰਨ ਲਿਆ ਕਿ ਡਿਲਿਵਰੀ ਕ੍ਰਮ = ਇਵੈਂਟ ਕ੍ਰਮ)
ਰਾਜ਼ ਦਾ ਲੈਣ (ਕੋਈ ਸਿਗਨੇਚਰ ਵਰਿਫਿਕੇਸ਼ਨ ਨਹੀਂ, ਤਾਂ ਅਸਲੀ ਅਤੇ ਨਕਲੀ ਵਿੱਚ ਫਰਕ ਨਹੀਂ ਕੀਤਾ ਜਾ ਸਕਦਾ)

ਵਾਸਤਵਿਕ ਲਕੜੀ ਦਾ ਮਕਸਦ ਸਧਾਰਨ ਹੈ: ਅਸਲ ਇਵੈਂਟ ਨੂੰ ਇੱਕ ਵਾਰੀ ਕਬੂਲ ਕਰੋ, ਨਕਲੀ ਨੂੰ ਰੱਦ ਕਰੋ, ਅਤੇ ਇੱਕ ਸਾਫ਼ ਟਰੇਲ ਛੱਡੋ ਤਾਂ ਕਿ ਤੁਸੀਂ ਗਾਹਕ ਦੀ ਰਿਪੋਰਟ ਨੂੰ ਮਿੰਟਾਂ ਵਿੱਚ ਡੀਬੱਗ ਕਰ ਸਕੋ।

Webhooks ਅਸਲ ਵਿੱਚ ਕਿਵੇਂ ਵਰਤਦੇ ਹਨ

Webhook ਸਿਰਫ਼ ਇੱਕ HTTP ਰਿਕਵੇਸਟ ਹੁੰਦੀ ਹੈ ਜੋ ਪ੍ਰੋਵਾਈਡਰ ਤੁਹਾਡੇ ਦੁਆਰਾ ਖੋਲ੍ਹੇ ਐਂਡਪੌਇੰਟ ਨੂੰ ਭੇਜਦਾ ਹੈ। ਤੁਸੀਂ ਇਸਨੂੰ API ਦੀ ਤਰ੍ਹਾਂ ਖਿੱਚਦੇ ਨਹੀਂ ਹੋ। ਸੈਂਡਰ ਇਹ ਤੁਰੰਤ ਧੱਕੇ ਦੇ ਕੇ ਭੇਜਦਾ ਹੈ ਜਦੋਂ ਕੁਝ ਹੁੰਦਾ ਹੈ, ਤੇ ਤੁਹਾਡੀ ਜ਼ਿੰਮੇਵਾਰੀ ਇਸਨੂੰ ਜਲਦੀ ਰਿਸੀਵ ਕਰਨਾ, ਜਵਾਬ ਦੇਣਾ ਅਤੇ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਪ੍ਰੋਸੈਸ ਕਰਨਾ ਹੈ।

ਅਮੂਮਨ ਡਿਲਿਵਰੀ ਵਿੱਚ ਇੱਕ ਬਾਡੀ ਹੁੰਦੀ ਹੈ (ਅਕਸਰ JSON) ਨਾਲ ਕੁਝ ਹੈਡਰ ਹੋਦੇ ਹਨ ਜੋ ਤੁਹਾਨੂੰ ਵੇਰੀਫਾਈ ਅਤੇ ਟ੍ਰੈਕ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦੇ ਹਨ। ਬਹੁਤ ਸਾਰੇ ਪ੍ਰੋਵਾਈਡਰ ਇੱਕ ਟਾਈਮਸਟੈਂਪ, ਇਕ ਇਵੈਂਟ ਕਿਸਮ (ਜਿਵੇਂ invoice.paid), ਅਤੇ ਇੱਕ ਯੂਨੀਕ ਇਵੈਂਟ ID ਸ਼ਾਮਿਲ ਕਰਦੇ ਹਨ ਜਿਸਨੂੰ ਤੁਸੀਂ ਡੁਪਲੀਕੇਟ ਪਛਾਣਣ ਲਈ ਸਟੋਰ ਕਰ ਸਕਦੇ ਹੋ।

ਜਿਹੜੀ ਗੱਲ ਟੀਮਾਂ ਨੂੰ ਚੌਕਾਉਂਦੀ ਹੈ: ਡਿਲਿਵਰੀ ਕਦੇ ਵੀ "ਸਹੀ ਤੌਰ ਤੇ ਇਕ ਵਾਰੀ" ਨਹੀਂ ਹੁੰਦੀ। ਅਕਸਰ ਪ੍ਰੋਵਾਈਡਰ "at least once" ਨੂੰ ਲੱਛਣ ਰੱਖਦੇ ਹਨ, ਜਿਸਦਾ ਮਤਲਬ ਹੈ ਇੱਕੋ ਇਵੈਂਟ ਕਈ ਵਾਰ ਆ ਸਕਦਾ ਹੈ, ਕਦੇ ਮਿੰਟਾਂ ਜਾਂ ਘੰਟਿਆਂ ਬਾਅਦ ਵੀ।

ਰੀਟ੍ਰਾਈ ਕਈ ਸਧਾਰਨ ਕਾਰਨਾਂ ਕਰਕੇ ਹੁੰਦੇ ਹਨ: ਤੁਹਾਡਾ ਸਰਵਰ ਸ্লੋ ਹੈ ਜਾਂ ਟਾਈਮਆਊਟ ਹੋ ਗਿਆ, ਤੁਸੀਂ 500 ਵਾਪਸ ਕੀਤਾ, ਉਨਾਂ ਦੇ ਨੈੱਟਵਰਕ ਨੇ ਤੁਹਾਡੀ 200 ਨਹੀਂ ਦੇਖੀ, ਜਾਂ ਡਿਪਲੋਏ/ਟ੍ਰੈਫਿਕ ਸਪਾਈਕ ਦੌਰਾਨ ਤੁਹਾਡੀ ਐਂਡਪੌਇੰਟ ਅਸਥਾਈ ਤੌਰ 'ਤੇ ਅਣਉਪਲਬਧ ਸੀ।

ਟਾਈਮਆਊਟ ਖਾਸ ਤੌਰ 'ਤੇ ਚੁਣੌਤੀਪੂਰਨ ਹੈ। ਤੁਹਾਡਾ ਸਰਵਰ ਰਿਕਵੇਸਟ ਪ੍ਰਾਪਤ ਕਰ ਸਕਦਾ ਹੈ ਅਤੇ ਅਦਾਇਗੀ ਤੱਕ ਪਹੁੰਚ ਕੇ ਵੀ ਪ੍ਰੋਸੈਸ ਕਰ ਲੈ, ਪਰ ਜਵਾਬ ਸੈਂਡਰ ਤੱਕ ਸਮੇਂ `ਤੇ ਨਹੀਂ ਪਹੁੰਚਦਾ। ਪ੍ਰੋਵਾਈਡਰ ਦੇ ਦਿੱਸ ਵਿੱਚ ਇਹ ਫੇਲ ਹੈ, ਇਸ ਲਈ ਉਹ ਰੀਟ੍ਰਾਈ ਕਰਦੇ ਹਨ। ਬਿਨਾਂ ਸੁਰੱਖਿਆ ਦੇ, ਤੁਸੀਂ ਇਕੋ ਇਵੈਂਟ ਨੂੰ ਦੋ ਵਾਰੀ ਪ੍ਰੋਸੈਸ ਕਰ ਲਉਗੇ।

ਇੱਕ ਵਧੀਆ ਸੋਚ ਇਹ ਹੈ ਕਿ HTTP ਰਿਕਵੇਸਟ ਨੂੰ "ਡਿਲਿਵਰੀ ਅਟੈਮਪਟ" ਮਾਨੋ, ਨਾ ਕਿ "ਇਵੈਂਟ"। ਇਵੈਂਟ ਆਪਣੀ ID ਨਾਲ ਪਛਾਣਿਆ ਜਾਂਦਾ ਹੈ। ਤੁਹਾਡੀ ਪ੍ਰੋਸੈਸਿੰਗ ਉਸ ID ਤੇ ਆਧਾਰਿਤ ਹੋਣੀ ਚਾਹੀਦੀ ਹੈ, ਨਾ ਕਿ ਇਹਦੇ ਅਧਾਰ ਤੇ ਕਿ ਪ੍ਰੋਵਾਈਡਰ ਤੁਹਾਨੂੰ ਕਿੰਨੀ ਵਾਰੀ ਕਾਲ ਕਰਦਾ ਹੈ।

ਸਧਾਰਨ ਸ਼ਬਦਾਂ ਵਿੱਚ webhook ਦਸਤਖ਼ਤ

Webhook ਦਸਤਖ਼ਤ ਇਸ ਗੱਲ ਦਾ ਸਬੂਤ ਹੈ ਕਿ ਸੈਂਡਰ ਈਹੀ ਵਾਕਈ ਉਹਨਾਂ ਨੇ ਭੇਜਿਆ ਸੀ ਅਤੇ ਵਿਚਕਾਰ ਵਿੱਚ ਬਦਲਿਆ ਨਹੀਂ ਗਿਆ। ਦਸਤਖ਼ਤ ਦੇ ਬਿਨਾਂ, ਕੋਈ ਵੀ ਜੋ ਤੁਹਾਡੇ webhook URL ਦਾ ਅਨੁਮਾਨ ਲਾ ਲੈਂਦਾ ਹੈ ਨਕਲੀ "payment succeeded" ਜਾਂ "user upgraded" ਇਵੈਂਟ ਪੋਸਟ ਕਰ ਸਕਦਾ ਹੈ। ਇਸ ਤੋਂ ਵੀ ਵੱਧ ਖ਼ਤਰਨਾਕ, ਇੱਕ ਅਸਲ ਇਵੈਂਟ ਰਸਤੇ ਵਿੱਚ ਤਬਦੀਲ ਕੀਤਾ ਜਾ ਸਕਦਾ ਹੈ (ਰਕਮ, ਗਾਹਕ ID, ਇਵੈਂਟ ਕਿਸਮ) ਅਤੇ ਫਿਰ ਵੀ ਤੁਹਾਡੇ ਐਪ ਨੂੰ ਸਹੀ ਲੱਗ ਸਕਦਾ ਹੈ।

ਸਭ ਤੋਂ ਆਮ ਪੈਟਰਨ HMAC ਨਾਲ ਸ਼ੇਅਰਡ ਸੀਕ੍ਰਿਟ ਹੁੰਦਾ ਹੈ। ਦੋਹਾਂ ਪਾਸੇ ਇੱਕੋ ਸੀਕ੍ਰਿਟ ਪਤਾ ਹੁੰਦਾ ਹੈ। ਸੈਂਡਰ ਸਹੀ ਬਾਇਟਸ (ਅਕਸਰ ਰਾ ਬਾਡੀ) 'ਤੇ HMAC ਬਣਾਉਂਦਾ ਹੈ ਅਤੇ ਸਿਗਨੇਚਰ ਨੂੰ ਬਾਡੀ ਦੇ ਨਾਲ ਭੇਜਦਾ ਹੈ। ਤੁਹਾਡੀ ਜ਼ਿੰਮੇਵਾਰੀ ਉਹੀ HMAC ਉਸੇ ਬਾਇਟਸ 'ਤੇ ਫਿਰ ਤੋਂ ਕੈਲਕੁਲੇਟ ਕਰਕੇ ਮੈਚ ਦੇਖਣੀ ਹੈ।

ਸਿਗਨੇਚਰ ਆਮ ਤੌਰ 'ਤੇ HTTP ਹੈਡਰ ਵਿੱਚ ਰੱਖੇ ਜਾਂਦੇ ਹਨ। ਕੁਝ ਪ੍ਰੋਵਾਈਡਰ ਟਾਈਮਸਟੈਂਪ ਵੀ ਸ਼ਾਮਿਲ ਕਰਦੇ ਹਨ ਤਾਂ ਜੋ ਤੁਸੀਂ replay protection ਜੋੜ ਸਕੋ। ਘੱਟ ਆਮ ਤੌਰ 'ਤੇ, ਸਿਗਨੇਚਰ JSON ਬਾਡੀ ਵਿੱਚ ਹੀ ਹੁੰਦਾ ਹੈ, ਜੋ ਖਤਰਨਾਕ ਹੈ ਕਿਉਂਕਿ ਪਾਰਸਰ ਜਾਂ ਰੀ-ਸਿਰੀਅਲਾਈਜ਼ੇਸ਼ਨ ਫਾਰਮੈਟ ਬਦਲ ਸਕਦਾ ਹੈ ਅਤੇ ਵੇਰੀਫਿਕੇਸ਼ਨ ਟੁੱਟ ਸਕਦੀ ਹੈ।

ਸਿਗਨੇਚਰ ਦੀ ਤੁਲਨਾ ਕਰਦੇ ਸਮੇਂ ਆਮ ਸਟਰਿੰਗ ਤુલਨਾ ਨਾ ਵਰਤੋ। ਨਾਰਮਲ ਤੁਲਨੀਆਂ ਸਮੇਂ-ਕਟਾਵ ਦੇ ਫਰਕ ਲੀਕ ਕਰ ਸਕਦੀਆਂ ਹਨ ਜੋ ਹਮਲਾਵਰ ਨੂੰ ਕਈ ਕੋਸ਼ਿਸ਼ਾਂ ਵਿੱਚ ਸਹੀ ਸਿਗਨੇਚਰ ਅੰਦਾਜ਼ਾ ਲਗਾਉਣ ਵਿੱਚ ਮਦਦ ਕਰਦੇ ਹਨ। ਆਪਣੇ ਭਾਸ਼ਾ ਜਾਂ ਕ੍ਰਿਪਟੋ ਲਾਇਬ੍ਰੇਰੀ ਤੋਂ constant-time comparison ਫੰਕਸ਼ਨ ਵਰਤੋ ਅਤੇ ਕਿਸੇ ਵੀ mismatch 'ਤੇ ਰੱਦ ਕਰੋ।

ਜੇ ਗਾਹਕ ਅਰਜ਼ ਕਰਦਾ ਹੈ “ਤੁਹਾਡੀ ਸਿਸਟਮ ਨੇ ਇੱਕ ਇਵੈਂਟ ਕਬੂਲ ਕੀਤਾ ਜੋ ਅਸੀਂ ਨਹੀਂ ਭੇਜਿਆ,” ਤਾਂ ਸਿਗਨੇਚਰ ਚੈੱਕ ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ। ਜੇ ਸਿਗਨੇਚਰ ਵੇਰੀਫਿਕੇਸ਼ਨ ਫੇਲ ਹੁੰਦੀ ਹੈ, ਤਾਂ ਸੰਭਵ ਹੈ ਕਿ ਸੀਕ੍ਰਿਟ ਮਿਸਮੈਚ ਹੈ ਜਾਂ ਤੁਸੀਂ ਗਲਤ ਬਾਇਟਸ ਤੇ ਹੈਸ਼ ਕਰ ਰਹੇ ਹੋ (ਉਦਾਹਰਨ ਲਈ, ਪਾਰਸ ਕੀਤਾ JSON ਬਜਾਏ ਰਾ ਬਾਡੀ)। ਜੇ ਇਹ ਪਾਸ ਹੁੰਦਾ ਹੈ, ਤਾਂ ਤੁਸੀਂ ਸੈਂਡਰ ਦੀ ਪਹਚਾਣ 'ਤੇ ਭਰੋਸਾ ਕਰ ਸਕਦੇ ਹੋ ਅਤੇ ਡਿਡਿਊਪਿੰਗ, ਆਰਡਰਿੰਗ, ਅਤੇ ਰੀਟ੍ਰਾਈਅਂ ਤੇ ਅੱਗੇ ਵਧ ਸਕਦੇ ਹੋ।

ਕਦਮ ਬਦ ਕਦਮ: webhook ਸਿਗਨੇਚਰ ਦੀ ਜਾਂਚ

ਭਰੋਸੇਯੋਗ webhook ਹੈਂਡਲਿੰਗ ਇੱਕ ਨਿੱਘੀ ਨੀਂਅਮ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦੀ ਹੈ: ਜੋ ਤੁਸੀਂ ਪ੍ਰਾਪਤ ਕੀਤਾ ਉਸਦੀ ਜਾਂਚ ਕਰੋ, ਜੋ ਤੁਸੀਂ ਚਾਹੁੰਦੇ ਸੋਚ ਕੇ ਨਹੀਂ।

ਸੁਰੱਖਿਅਤ ਤਰੀਕਾ

ਜਿਵੇਂ ਆਇਆ, ਰਾ ਰਿਕਵੇਸਟ ਬਾਡੀ ਨੂੰ ਠੀਕ ਠੀਕ ਉਸੇ ਰੂਪ ਵਿੱਚ ਕੈਪਚਰ ਕਰੋ। ਸਿਗਨੇਚਰ ਜਾਂਚ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ JSON ਪਾਰਸ ਅਤੇ ਰੀ-ਸਿਰੀਅਲਾਈਜ਼ ਨਾ ਕਰੋ। ਛੋਟੇ ਫ਼ਰਕ (ਵਾਈਟਸਪੇਸ, ਕੀ-ਆਰਡਰ, ਯੂਨੀਕੋਡ) ਬਾਇਟਸ ਬਦਲ ਸਕਦੇ ਹਨ ਅਤੇ ਸਹੀ ਸਿਗਨੇਚਰ ਨੂੰ ਗਲਤ ਦਿਖਾ ਸਕਦੇ ਹਨ।

ਫਿਰ ਉਹੀ payload ਬਣਾਓ ਜੋ ਤੁਹਾਡਾ ਪ੍ਰੋਵਾਈਡਰ ਤੁਹਾਨੂੰ ਸਾਇਨ ਕਰਨ ਲਈ ਉਮੀਦ ਕਰਦਾ ਹੈ। ਬਹੁਤ ਸਿਸਟਮ ਇੱਕ ਸਟਰਿੰਗ timestamp + "." + raw_body ਸਾਇਨ ਕਰਦੇ ਹਨ। ਟਾਈਮਸਟੈਂਪ ਫੁਲ-ਡੈਕੋਰੇਸ਼ਨ ਨਹੀਂ ਹੈ—ਉਹ ਇਸ ਲਈ ਹੈ ਤਾਂ ਕਿ ਤੁਸੀਂ ਪੁਰਾਣੀਆਂ ਰਿਕਵੇਸਟਾਂ ਰੱਦ ਕਰ ਸਕੋ।

ਸਹੀ ਸੀਕ੍ਰਿਟ ਅਤੇ ਹ್ಯਾਸ਼ (ਅਕਸਰ SHA-256) ਨਾਲ HMAC ਕੈਲਕੁਲੇਟ ਕਰੋ। ਸੀਕ੍ਰਿਟ ਨੂੰ ਸੁਰੱਖਿਅਤ ਸਟੋਰ ਵਿੱਚ ਰੱਖੋ ਅਤੇ ਪਾਸਵਰਡ ਵਾਂਗ ਉਸਦਾ ਇਲਾਜ ਕਰੋ।

ਅਖੀਰ ਵਿੱਚ, ਆਪਣੇ ਕੈਲਕੁਲੇਟ ਕੀਤੇ ਮੁੱਲ ਨੂੰ ਸਿਗਨੇਚਰ ਹੈਡਰ ਨਾਲ constant-time comparison ਨਾਲ ਤੁਲਨਾ ਕਰੋ। ਜੇ ਮੈਚ ਨਾ ਹੋਵੇ, 4xx ਰਿਟਰਨ ਕਰੋ ਅਤੇ ਰੋਕ ਦਿਓ। ਕਦੇ ਵੀ "ਫਿਰ ਵੀ ਕਬੂਲ ਕਰੋ" ਨਾ ਕਰੋ।

ਇਕ ਤੁਰੰਤ ਚੈੱਕਲਿਸਟ:

ਬਾਡੀ ਨੂੰ ਬਾਇਟਸ ਵਜੋਂ ਇੱਕ ਵਾਰੀ ਪੜ੍ਹੋ, ਸਟੋਰ ਕਰੋ, ਅਤੇ ਉਹੀ ਬਾਇਟਸ ਵੇਰੀਫਿਕੇਸ਼ਨ ਲਈ ਵਰਤੋ।
ਸਾਇਨ ਕੀਤੀ ਸਟਰਿੰਗ ਨੂੰ ਬਿਲਕੁਲ ਦੁਬਾਰਾ ਬਣਾਓ, ਜਿਨ੍ਹਾਂ ਵਿੱਚ(separator) ਅਤੇ ਟਾਈਮਸਟੈਂਪ ਫਾਰਮੈਟਿੰਗ ਸ਼ਾਮਿਲ ਹੈ।
ਸਹੀ ਸੀਕ੍ਰਿਟ ਅਤੇ ਐਲਗੋਰਿਦਮ ਨਾਲ HMAC ਕਲਕੁਲੇਟ ਕਰੋ।
ਸਿਗਨੇਚਰ ਮੁੱਲਾਂ ਦੀ ਸੁਰੱਖਿਅਤ ਤੁਲਨਾ ਕਰੋ ਅਤੇ mismatch ਨੂੰ ਰੱਦ ਕਰੋ।
ਕਿ Verification ਕਿਉਂ ਫੇਲ ਹੋਇਆ, ਇਹ ਲੌਗ ਕਰੋ (missing header, bad timestamp, mismatch) ਪਰ ਸੀਕ੍ਰਿਟ ਜਾਂ ਪੂਰੀ ਸਿਗਨੇਚਰ ਲੌਗ ਨਾ ਕਰੋ।

ਇੱਕ ਛੋਟਾ ਉਦਾਹਰਨ

ਇੱਕ ਗਾਹਕ ਰਿਪੋਰਟ ਕਰਦਾ ਹੈ “webhooks ਕੰਮ ਕਰਨਾ ਬੰਦ ਕਰ ਦਿੱਤੇ” ਬਾਅਦ ਤੁਸੀਂ JSON ਪਾਰਸਿੰਗ ਮੱਧਲਵੇਅਰ ਸ਼ਾਮਿਲ ਕੀਤਾ। ਤੁਸੀਂ ਜ਼ਿਆਦातर ਸਿਗਨੇਚਰ mismatches ਦੇਖਦੇ ਹੋ, ਵੱਡੇ payloads 'ਤੇ ਖਾਸ। ਠੀਕ ਕਰਨ ਲਈ ਆਮ ਤੌਰ 'ਤੇ ਸਿਗਨੇਚਰ ਮੋੜ ਤੋਂ ਪਹਿਲਾਂ ਰਾ ਬਾਡੀ ਵਰਤ ਕੇ ਵੇਰੀਫਾਈ ਕਰਨਾ ਅਤੇ ਇਹ ਲੌਗ ਕਰਨਾ ਕਿ ਕਿਹੜਾ ਕਦਮ ਫੇਲ ਹੋਇਆ (ਉਦਾਹਰਨ: “signature header missing” ਬਨਾਮ “timestamp outside allowed window”) ਹਾਂਦਾ ਹੈ। ਇਹ ਇੱਕ ਛੋਟੀ ਜਹੀ ਗੱਲ ਡੀਬੱਗਿੰਗ ਦਾ ਸਮਾਂ ਘੰਟਿਆਂ ਤੋਂ ਮਿੰਟਾਂ 'ਚ ਘਟਾ ਸਕਦੀ ਹੈ।

Idempotency keys: ਇੱਕ ਵਾਰੀ ਕਬੂਲ, ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ

ਪ੍ਰੋਵਾਈਡਰ ਰੀਟ੍ਰਾਈ ਕਰਦੇ ਹਨ ਕਿਉਂਕਿ ਡਿਲਿਵਰੀ ਗਾਰੰਟੀਡ ਨਹੀਂ ਹੁੰਦੀ। ਤੁਹਾਡਾ ਸਰਵਰ ਇਕ ਮਿੰਟ ਲਈ ਡਾਊਨ ਹੋ ਸਕਦਾ ਹੈ, ਇੱਕ ਨੈੱਟਵਰਕ ਹੌਪ ਰਿਕਵੇਸਟ ਨੂੰ ਡ੍ਰਾਪ ਕਰ ਸਕਦਾ ਹੈ, ਜਾਂ ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਟਾਈਮਆਊਟ ਹੋ ਸਕਦਾ ਹੈ। ਪ੍ਰੋਵਾਈਡਰ ਸੋਚਦਾ ਹੈ "ਸੰਭਵ ਹੈ ਕਿ ਇਹ ਹੋ ਗਿਆ" ਅਤੇ ਇਕੋ ਇਵੈਂਟ ਮੁੜ ਭੇਜਦਾ ਹੈ।

Idempotency ਕੀ ਉਸ ਰਸੀਦ ਨੰਬਰ ਵਾਂਗ ਹੈ ਜੋ ਤੁਸੀਂ ਵਰਤਦੇ ਹੋ ਤਾਂ ਕਿ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਪ੍ਰੋਸੈਸ ਕੀਤੇ ਇਵੈਂਟ ਨੂੰ ਪਛਾਣ ਸਕੋ। ਇਹ ਸੁਰੱਖਿਆ ਫੀਚਰ ਨਹੀਂ ਹੈ, ਅਤੇ ਸੀਗਨੇਚਰ ਵੇਰੀਫਿਕੇਸ਼ਨ ਦਾ ਬਦਲ ਨਹੀਂ। ਇਹ ਰੇਸ ਕਨਡੀਸ਼ਨਾਂ ਨੂੰ ਠੀਕ ਨਹੀਂ ਕਰਦਾ ਜਦ ਤੱਕ ਤੁਸੀਂ ਇਸਨੂੰ concurrency ਹਾਲਾਤ ਅੰਦਰ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਸਟੋਰ ਅਤੇ ਚੈੱਕ ਨਹੀਂ ਕਰਦੇ।

ਕੀ ਚੁਣਨਾ ਹੈ ਇਹ ਇਸ ਗੱਲ 'ਤੇ ਨਿਰਭਰ ਕਰਦਾ ਹੈ ਜੋ ਪ੍ਰੋਵਾਈਡਰ ਤੁਹਾਨੂੰ ਦਿੰਦਾ ਹੈ। ਉਹਨਾਂ ਮੁੱਲ ਨੂੰ ਪਸੰਦ ਕਰੋ ਜੋ ਰੀਟ੍ਰਾਈਅਾਂ ਦੌਰਾਨ ਸਥਿਰ ਰਹਿੰਦਾ:

ਇਵੈਂਟ ID (ਜਦੋਂ ਇੱਕ ਇਵੈਂਟ ਇੱਕ ਬਿਜ਼ਨਸ ਚੇਂਜ ਨਾਲ ਨਕਲ ਖਾਂਦਾ ਹੋਵੇ ਤਾਂ ਸਭ ਤੋਂ ਚੰਗਾ)
ਡਿਲਿਵਰੀ ID ਜਾਂ ਮੈਸੇਜ ID (ਜਦੋਂ ਰੀਟ੍ਰਾਈ ਦੌਰਾਨ ਇੱਕੋ ਡਿਲਿਵਰੀ ਆਈਡੈਂਟੀਫਾਇਰ ਰਿਹਾ ਹੋਵੇ)
ਸਥਿਰ ਫੀਲਡਾਂ ਦਾ ਹੈਸ਼ (ਜਦ ਕੋਈ ID ਨਾਹ ਹੋਵੇ ਤਾਂ ਆਖ਼ਰੀ ਚੋਣ)

ਜਦੋਂ ਤੁਸੀਂ webhook ਪ੍ਰਾਪਤ ਕਰੋ, ਪਹਿਲਾਂ ਕੀ ਨੂੰ ਸਟੋਰੇਜ ਵਿੱਚ ਇੱਕ ਯੂਨੀਕನੈੱਸ ਨਿਯਮ ਨਾਲ ਲਿਖੋ ਤਾਂ ਕਿ ਸਿਰਫ ਇੱਕ ਰਿਕਵੇਸਟ "ਜਿੱਤੇ"। ਫਿਰ ਇਵੈਂਟ ਨੂੰ ਪ੍ਰੋਸੈਸ ਕਰੋ। ਜੇ ਤੁਸੀਂ ਉਹੀ ਕੀ ਫਿਰ ਤੋਂ ਵੇਖੋ, ਤਾਂ ਸਫਲਤਾ ਰਿਟਰਨ ਕਰੋ ਬਿਨਾਂ ਫਿਰ ਦੋ ਵਾਰੀ ਕੰਮ ਕਰਨ ਦੇ।

ਆਪਣੇ ਸਟੋਰ ਕੀਤੇ “ਰਸੀਦ” ਨੂੰ ਛੋਟਾ ਪਰ ਲਾਭਕਾਰੀ ਰੱਖੋ: ਕੀ, ਪ੍ਰੋਸੈਸਿੰਗ ਸਟੇਟਸ (received/processed/failed), ਟਾਈਮਸਟੈਂਪ (first seen/last seen), ਅਤੇ ਇੱਕ ਘੱਟ ਸਾਰ (ਇਵੈਂਟ ਕਿਸਮ ਅਤੇ ਸਬੰਧਤ ਆਬਜੈਕਟ ID)। ਬਹੁਤ ਸਾਰੀਆਂ ਟੀਮਾਂ ਕੁੰਜੀਆਂ ਨੂੰ 7 ਤੋਂ 30 ਦਿਨ ਤੱਕ ਰੱਖਦੀਆਂ ਹਨ ਤਾਂ ਕਿ ਦੇਰ ਨਾਲ ਰੀਟ੍ਰਾਈਅں ਅਤੇ ਜ਼ਿਆਦਾਤਰ ਗਾਹਕ ਰਿਪੋਰਟਾਂ ਕਵਰ ਹੋ ਸਕਣ।

Replay ਸੁਰੱਖਿਆ ਬਿਨਾਂ ਅਸਲੀ ਟ੍ਰੈਫਿਕ ਨੂੰ ਰੋਕੇ

Host your webhook service

Set up hosting and deployment for your webhook service without extra tooling.

Start Building

Replay protection ਇੱਕ ਆਸਾਨ ਪਰ ਖ਼ਤਰਨਾਕ ਸਮੱਸਿਆ ਨੂੰ ਰੋਕਦੀ ਹੈ: ਕੋਈ ਵਿਅਕਤੀ ਇੱਕ ਅਸਲ webhook ਰਿਕਵੇਸਟ (ਜਿਸ ਦੇ ਨਾਲ ਸਹੀ ਸਿਗਨੇਚਰ ਹੋਵੇ) ਕੈਪਚਰ ਕਰ ਲੈਂਦਾ ਹੈ ਅਤੇ ਬਾਅਦ ਵਿੱਚ ਦੁਬਾਰਾ ਭੇਜ ਦਿੰਦਾ ਹੈ। ਜੇ ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਹਰ ਡਿਲਿਵਰੀ ਨੂੰ ਨਵਾਂ ਮੰਨਦਾ ਹੈ, ਉਹ replay duplicate refunds, ਵੱਖ-ਵੱਖ user invites, ਜਾਂ ਦੁਹਰਾਏ ਹੋਏ ਸਟੇਟਸ ਚੇਂਜ ਤਿਆਰ ਕਰ ਸਕਦਾ ਹੈ।

ਆਮ ਤਰੀਕਾ payload ਦੇ ਨਾਲ ਨਾਲ ਟਾਈਮਸਟੈਂਪ ਨੂੰ ਵੀ sign ਕਰਨਾ ਹੁੰਦਾ ਹੈ। ਤੁਹਾਡਾ webhook ਐਸੇ ਹੈਡਰ ਭੇਜੇ ਜਿਵੇਂ X-Signature ਅਤੇ X-Timestamp। ਪ੍ਰਾਪਤੀ 'ਤੇ, ਸਿਗਨੇਚਰ ਦੀ ਜਾਂਚ ਕਰੋ ਅਤੇ ਇਹ ਵੀ ਵੇਰਿਫਾਈ ਕਰੋ ਕਿ ਟਾਈਮਸਟੈਂਪ ਇੱਕ ਛੋਟੀਵੀਂ ਵਿੰਡੋ ਦੇ ਅੰਦਰ ਤਾਜ਼ਾ ਹੈ।

ਕਲਾਕ ਡ੍ਰਿਫਟ ਆਮ ਤੌਰ 'ਤੇ ਗਲਤ ਰੱਦੀਆਂ ਦਾ ਕਾਰਨ ਹੁੰਦੀ ਹੈ। ਤੁਹਾਡੇ ਸਰਵਰ ਅਤੇ ਸੈਂਡਰ ਦੇ ਸਰਵਰ ਕੁਝ ਮਿੰਟਾਂ ਵਿੱਚ ਵੱਖ-ਵੱਖ ਹੋ ਸਕਦੇ ਹਨ, ਅਤੇ ਨੈੱਟਵਰਕ ਡਿਲੇ ਵਿੱਚ ਰਿਕਵੇਸਟ ਆ ਸਕਦੀ ਹੈ। ਇੱਕ ਗ੍ਰੇਸ ਰੱਖੋ ਅਤੇ ਰੀਜੈਕਸ਼ਨ ਦਾ ਕਾਰਨ ਲੌਗ ਕਰੋ।

ਇਹ ਤਰਕੀਬੀ ਨਿਯਮ ਅਚھی ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦੇ ਹਨ:

ਸਵੀਕਾਰੋ ਸਿਰਫ ਜੇ abs(now - timestamp) <= window (ਉਦਾਹਰਨ ਲਈ, 5 ਮਿੰਟ ਨਾਲ ਛੋਟਾ ਗ੍ਰੇਸ)।
ਅਸਲ ਸੁਰੱਖਿਆ ਨੈੱਟ idempotency ਉੱਤੇ ਨਿਰਭਰ ਕਰੋ। ਵੀਂਡੋ ਦੇ ਅੰਦਰ ਵੀ, ਰੀਟ੍ਰਾਈ ਦੁਹਰਾਏ ਨਹੀਂ ਹੋਣੇ ਚਾਹੀਦੇ।
ਜੇ ਤੁਸੀਂ ਸਮੇਂ ਲਈ ਰੱਦ ਕਰੋ, ਇੱਕ ਸਾਫ਼ 4xx ਲੌਟਾਓ ਅਤੇ ਪ੍ਰਾਪਤ ਟਾਈਮਸਟੈਂਪ ਤੇ ਤੁਹਾਡੇ ਸਰਵਰ ਸਮੇਂ ਨੂੰ ਲੌਗ ਕਰੋ।

ਜੇ ਟਾਈਮਸਟੈਂਪ ਗੁੰਮ ਹਨ, ਤਾਂ ਤੁਸੀਂ ਸਮੇਂ ਆਧਾਰਿਤ ਸੱਚੀ replay protection ਨਹੀਂ ਕਰ ਸਕਦੇ। ਇਸ ਸਥਿਤੀ ਵਿੱਚ, idempotency 'ਤੇ ਹੋਰ ਜ਼ੋਰ ਦਿਓ (ਡੁਪਲੀਕੇਟ ਇਵੈਂਟ IDs ਸਟੋਰ ਅਤੇ ਰੱਦ ਕਰੋ) ਅਤੇ ਅਗਲੇ webhook ਵਰਜ਼ਨ ਵਿੱਚ ਟਾਈਮਸਟੈਂਪ ਲਾਜ਼ਮੀ ਕਰਨ 'ਤੇ ਵਿਚਾਰ ਕਰੋ।

ਸੀਕ੍ਰਿਟ ਰੋਟੇਸ਼ਨ ਵੀ ਅਹੰਕਾਰਪੂਰਕ ਹੈ। ਜੇ ਤੁਸੀਂ ਸਾਇਨਿੰਗ ਸੀਕ੍ਰਿਟ ਰੋਟੇਟ ਕਰਦੇ ਹੋ, ਤਾਂ ਛੋਟੇ overlap ਅਰਸੇ ਲਈ ਕਈ ਐਕਟਿਵ ਸੀਕ੍ਰਿਟ ਰੱਖੋ। ਨਵੇਂ ਸੀਕ੍ਰਿਟ ਨੂੰ ਪਹਿਲਾਂ verify ਕਰੋ, ਫਿਰ ਪੁਰਾਣੇ ਵਾਲਿਆਂ 'ਤੇ fallback ਕਰੋ। ਇਹ ਰੋਲਆਉਟ ਦੌਰਾਨ ਗਾਹਕ ਬਰਾਬਰੀ ਤੋਂ ਬਚਾਉਂਦਾ ਹੈ। ਜੇ ਤੁਹਾਡੀ ਟੀਮ ਜਲਦੀ ਨਾਲ ਐਂਡਪੌਇੰਟ ਸ਼ਿਪ ਕਰਦੀ ਹੈ (ਉਦਾਹਰਨ ਲਈ, Koder.ai ਤੇ ਕੋਡ ਜਨਰੇਟ ਕਰਨਾ ਅਤੇ ਸ్నੈਪਸ਼ਾਟਸ/ਰੋਲਬੈਕ ਵਰਤਣਾ), ਤਦ ਇਹ overlap ਵਿੰਡੋ ਮਦਦਗਾਰ ਰਹਿੰਦੀ ਹੈ ਕਿਉਂਕਿ ਪੁਰਾਣੇ ਵਰਜ਼ਨ ਵੀ ਥੋੜ੍ਹੇ ਸਮੇਂ ਲਈ ਲਾਈਵ ਰਹਿ ਸਕਦੇ ਹਨ।

ਹੈਂਡਲਰ ਇਸ ਤਰ੍ਹਾਂ ਡਿਜ਼ਾਈਨ ਕਰੋ ਕਿ ਰੀਟ੍ਰਾਈ ਤੁਹਾਨੂੰ ਨੁਕਸਾਨ ਨਾ ਪਹੁੰਚਾਉਣ

ਰੀਟ੍ਰਾਈ ਆਮ ਗੱਲ ਹੈ। ਧਾਰਨਾ ਕਰੋ ਕਿ ਹਰ ਡਿਲਿਵਰੀ ਨਕਲ, ਦੇਰ ਜਾਂ ਗਲਤ ਆਰਡਰ ਵਿੱਚ ਹੋ ਸਕਦੀ ਹੈ। ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਉਸੇ ਤਰੀਕੇ ਨਾਲ ਕੰਮ ਕਰੇ ਜੇ ਉਹ ਇੱਕ ਵਾਰੀ ਵੇਖੇ ਜਾਂ ਪੰਜ ਵਾਰੀ।

ਰਿਕਵੇਸਟ ਰਾਹ ਨੂੰ ਛੋਟਾ ਰੱਖੋ। ਸਿਰਫ ਜ਼ਰੂਰੀ ਕੰਮ ਕਰੋ ਤਾਂ ਕਿ ਆਦਾਨ-ਪ੍ਰदान ਤੇਜ਼ ਹੋਵੇ, ਅਤੇ ਭਾਰੀ ਕੰਮ ਨੂੰ ਬੈਕਗ੍ਰਾਊਂਡ ਜੌਬ 'ਤੇ ਭੇਜ ਦਿਓ।

ਇਕ ਸਧਾਰਨ ਪੈਟਰਨ ਜੋ ਪ੍ਰੋਡ ਵਿੱਚ ਚੰਗਾ ਕੰਮ ਕਰਦਾ ਹੈ:

ਬੇਸਿਕ ਦੀ ਜਾਂਚ ਕਰੋ (method, content type, required headers)
ਪ੍ਰਤਾਤਮਾ (signature) ਵੇਰੀਫਾਈ ਕਰੋ ਅਤੇ ਜੋ ਵੀ fail ਹੋ ਉਹ ਰੱਦ ਕਰੋ
Payload ਨੂੰ parse ਅਤੇ validate ਕਰੋ
ਇਵੈਂਟ ID (ਜਾਂ idempotency ਕੀ) ਨਾਲ dedupe ਕਰੋ ਇੱਕ ਟੇਬਲ ਵਿੱਚ ਯੂਨੀਕ ਕਨਸਟਰੇਂਟ ਨਾਲ
ਕੰਮ ਨੂੰ event ID ਦੇ ਨਾਲ queue ਵਿੱਚ ਪਾਓ, ਫਿਰ ਜਵਾਬ ਦਿਓ

2xx ਸਿਰਫ ਉਸ ਵੇਲੇ ਰਿਟਰਨ ਕਰੋ ਜਦੋਂ ਤੁਸੀਂ ਸਿਗਨੇਚਰ verify ਕਰ ਲਿਆ ਹੋਵੇ ਅਤੇ ਇਵੈਂਟ ਨੂੰ ਰਿਕਾਰਡ (ਜਾਂ queued) ਕਰ ਦਿੱਤਾ ਹੋਵੇ। ਜੇ ਤੁਸੀਂ 200 ਦੇ ਦਿੱਤਾ ਪਹਿਲਾਂ ਹੀ ਬਿਨਾਂ ਕੁਝ ਸੇਵ ਕੀਤੇ, ਤਾਂ ਤੁਸੀਂ ਕਰੈਸ਼ ਦੌਰਾਨ ਇਵੈਂਟ ਗੁਆ ਸਕਦੇ ਹੋ। ਜੇ ਤੁਸੀਂ ਭਾਰੀ ਕੰਮ ਜਵਾਬ ਦੇਣ ਤੋਂ ਪਹਿਲਾਂ ਕਰਦੇ ਹੋ, ਤਾਂ ਟਾਈਮਆਊਟ ਰੀਟ੍ਰਾਈ ਨੂੰ trigger ਕਰਦੇ ਹਨ ਅਤੇ ਤੁਸੀਂ ਸਾਈਡ-ਇਫੈਕਟ ਦੁਹਰਾਂਗੇ।

ਸਲੋ ਡਾਊਨਸਟਰੀਮ ਸਿਸਟਮਸ ਹੀ ਮੁੱਖ ਕਾਰਨ ਹਨ ਕਿ ਰੀਟ੍ਰਾਈ ਦਰਦਨਾਕ ਬਣ ਜਾਂਦੇ ਹਨ। ਜੇ ਤੁਹਾਡਾ ਇਮੇਲ ਪ੍ਰੋਵਾਈਡਰ, CRM, ਜਾਂ ਡੇਟਾਬੇਸ ਸਲੋ ਹੈ, ਤਾਂ ਇੱਕ ਕੁਯੂ ਉਸ ਡਿਲੇ ਨੂੰ ਸੋਖ ਲੈਵੇ। ਵਰਕਰ ਬੈਕਆਫ ਨਾਲ ਰੀਟ੍ਰਾਈ ਕਰ ਸਕਦਾ ਹੈ, ਅਤੇ ਤੁਸੀਂ stuck jobs ਉੱਤੇ ਅਲਾਰਟ ਕਰ ਸਕਦੇ ਹੋ ਬਿਨਾਂ ਸੈਂਡਰ ਨੂੰ ਰੋਕੇ।

ਆਊਟ-ਆਫ-ਆਰਡਰ ਇਵੈਂਟ ਵੀ ਹੁੰਦੇ ਹਨ। ਉਦਾਹਰਨ ਵਜੋਂ, subscription.updated ਪਹਿਲਾਂ ਆ ਸਕਦਾ ਹੈ subscription.created ਤੋਂ। ਵਰਤੋਂਕਾਰ ਸਟੇਟ ਨੂੰ ਚੈੱਕ ਕਰਕੇ ਬਦਲਾਅ ਲੱਗਾਓ, upserts ਦੀ ਵਰਤੋਂ ਕਰੋ, ਅਤੇ “not found” ਨੂੰ ਇੱਕ ਅਜਿਹੇ ਕਾਰਨ ਵਜੋਂ ਦੇਖੋ ਜਿਸਨੂੰ ਬਾਅਦ ਵਿੱਚ (ਉਚਿਤ ਹੋਵੇ ਤਾਂ) ਰੀਟ੍ਰਾਈ ਕਰਨਾ ਚਾਹੀਦਾ ਹੈ ਨਾ ਕਿ ਸਥਾਈ ਫੇਲ ਵਜੋਂ।

ਆਮ ਗਲਤੀਆਂ ਜੋ ਲੰਮੇ ਤਲਾਸ਼ ਵਾਲੇ ਬੱਗ ਬਣਾਉਂਦੀਆਂ ਹਨ

Build a safer webhook handler

Generate a signed, idempotent webhook endpoint from a simple chat prompt.

Try Free

ਕਈ “ਰੈਂਡਮ” webhook ਮੁੱਦੇ ਆਪਣੀ ਹੀ ਨਾ-ਸਚਾਈ ਦੀ ਬਨਾਈ ਹੋਈਆਂ ਹੁੰਦੀਆਂ ਹਨ। ਉਹ ਫਲੇਕੀ ਨੈਟਵਰਕ ਵਾਂਗ ਨਹੀਂ ਲੱਗਦੀਆਂ, ਪਰ ਇਹ ਇਕ ਰੁਟੀਨ ਪੈਟਰਨ ਵਿੱਚ ਦੁਹਰਾਉਂਦੀਆਂ ਹਨ, ਆਮ ਤੌਰ 'ਤੇ ਡਿਪਲੋਏ, ਸੀਕ੍ਰਿਟ ਰੋਟੇਸ਼ਨ, ਜਾਂ parsing ਵਿੱਚ ਛੋਟੀ ਤਬਦੀਲੀ ਤੋਂ ਬਾਅਦ।

ਸਭ ਤੋਂ ਆਮ ਸਿਗਨੇਚਰ ਬੱਗ ਗਲਤ ਬਾਇਟਸ ਤੇ ਹੈਸ਼ ਕਰਨਾ ਹੈ। ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ JSON ਪਾਰਸ ਕਰਦੇ ਹੋ, ਤੁਹਾਡਾ ਸਰਵਰ ਇਹਨੂੰ ਫਿਰ ਤੋਂ ਫਾਰਮੈਟ ਕਰ ਸਕਦਾ ਹੈ (ਵਾਈਟਸਪੇਸ, ਕੀ-ਆਰਡਰ, ਨੰਬਰ ਫਾਰਮੈਟਿੰਗ)। ਫਿਰ ਤੁਸੀਂ ਸਿਗਨੇਚਰ ਨੂੰ ਇੱਕ ਵੱਖਰੇ ਬਾਡੀ ਦੇ ਖਿਲਾਫ਼ verify ਕਰ ਰਹੇ ਹੋ ਜੋ ਸੈਂਡਰ ਨੇ ਸਾਇਨ ਕੀਤਾ ਸੀ, ਅਤੇ ਵੇਰੀਫਿਕੇਸ਼ਨ ਫੇਲ ਹੋ ਜਾਂਦੀ ਹੈ ਭਾਵੇਂ payload ਅਸਲੀ ਹੋਵੇ। ਹਮੇਸ਼ਾ ਰਾ ਬਾਡੀ ਬਾਇਟਸ 'ਤੇ verify ਕਰੋ।

ਅਗਲਾ ਵੱਡਾ ਗਲਤ ਸਰੋਤ ਸੀਕ੍ਰਿਟ ਹੁੰਦੀ ਹੈ। ਟੀਮਾਂ ਸਟੇਜਿੰਗ ਵਿੱਚ ਟੈਸਟ ਕਰਦੀਆਂ ਹਨ ਪਰ ਗਲਤੀ ਨਾਲ ਪ੍ਰੋਡ ਸੀਕ੍ਰਿਟ ਨਾਲ verify ਕਰ ਲੈਂਦੀਆਂ ਹਨ, ਜਾਂ ਰੋਟੇਸ਼ਨ ਤੋਂ ਬਾਅਦ ਪੁਰਾਣਾ ਸੀਕ੍ਰਿਟ ਰੱਖ ਜਾਂਦੀਆਂ ਹਨ। ਜਦ ਗਾਹਕ ਦੱਸਦਾ ਹੈ “ਸਿਰਫ਼ ਇੱਕ environment ਵਿੱਚ fail ਹੋ ਰਿਹਾ ਹੈ,” ਤਾਂ ਪਹਿਲਾਂ ਗਲਤ ਸੀਕ੍ਰਿਟ ਜਾਂ ਗਲਤ ਕੰਫਿਗ ਧਾਰਨਾ ਕਰੋ।

ਕੁਝ ਗਲਤੀਆਂ ਜੋ ਲੰਬੇ ਜਾਂਚ-ਪੜਤਾਲ ਵਿੱਚ ਲੈ ਜਾਂਦੀਆਂ ਹਨ:

ਡੀਬੱਗ ਕਰਨ ਲਈ ਪੂਰੀ ਬਾਡੀ ਲੌਗ ਕਰਨਾ, ਫਿਰ ਟੋਕਨ, ਈਮੇਲ, ਜਾਂ ਭੁਗਤਾਨ ਡੀਟੇਲ ਲੌਗ ਹੋ ਜਾਣਾ
500 ਵਾਪਸ ਕਰਦੇ ਹੋਏ ਵੀ ਸਾਈਡ-ਇਫੈਕਟ ਕਰਨਾ (ਈਮੇਲ ਭੇਜਨਾ, ਆਰਡਰ ਅਪਡੇਟ) — ਰੀਟ੍ਰਾਈ ਇਹਨਾਂ ਨੂੰ ਦੁਹਰਾਏਗਾ
ਇੱਕ idempotency ਕੀ ਵਰਤਣਾ ਜੋ ਸਚ-ਮੁਚ ਯੂਨੀਕ ਨਹੀਂ (ਉਦਾਹਰਨ ਲਈ, ਇਵੈਂਟ ਕਿਸਮ + ਮਿਨਟ). ਅਸਲ ਇਵੈਂਟ ਨੂੰ "ਡੁਪਲਿਕੇਟ" ਵਜੋਂ ਡਰੌਪ ਕੀਤਾ ਜਾ ਸਕਦਾ ਹੈ
2xx ਜਵਾਬ ਨੂੰ "processed" ਮੰਨਣਾ, ਜਦ ਤੁਹਾਡਾ ਕੋਡ ਸਿਰਫ਼ ਕੰਮ ਨੂੰ queue ਕੀਤਾ ਹੋਵੇ ਜੋ ਬਾਅਦ ਵਿੱਚ fail ਕਰ ਗਿਆ

ਉਦਾਹਰਨ: ਇੱਕ ਗਾਹਕ ਕਹਿੰਦਾ ਹੈ “order.paid ਕਦੇ ਨਹੀਂ ਆਇਆ।” ਤੁਸੀਂ ਵੇਖਦੇ ਹੋ ਕਿ ਸਿਗਨੇਚਰ ਫੇਲ ਹੁੰਦੇ ਨੇ ਬਾਅਦ ਇੱਕ ਰਿਫੈਕਟਰ ਜਿਸਨੇ request parsing middleware ਬਦਲ ਦਿੱਤਾ। ਮੱਧਲਵੇਅਰ ਰਾ ਬਾਡੀ ਪੜ੍ਹਦਾ ਅਤੇ ਰੀ-ਐਨਕੋਡ ਕਰਦਾ ਸੀ, ਇਸ ਲਈ ਤੁਹਾਡੀ ਸਿਗਨੇਚਰ ਚੈੱਕ ਹੁਣ ਸੋਧੀ ਹੋਈ ਬਾਡੀ ਵਰਤ ਰਿਹਾ ਹੈ। ਫਿਕਸ ਸਧਾਰਨ ਹੈ, ਪਰ ਸਿਰਫ ਜੇ ਤੁਸੀਂ ਇਸਨੂੰ ਦੇਖਣ ਦੀ ਸੋਚੋ।

ਗਾਹਕ-ਰਿਪੋਰਟ ਕੀਤੀਆਂ ਫੇਲੀਆਂ ਨੂੰ ਤੇਜ਼ੀ ਨਾਲ ਡੀਬੱਗ ਕਰੋ

ਜਦੋਂ ਗਾਹਕ ਕਹਿੰਦਾ ਹੈ “ਤੁਹਾਡਾ webhook ਨਹੀਂ ਚਲਿਆ,” ਇਸਨੂੰ ਇੱਕ ਟਰੇਸ ਸਮੱਸਿਆ ਵਜੋਂ ਲੋ, ਨਾ ਕਿ ਅਨੁਮਾਨ ਵਜੋਂ। ਇੱਕ ਸਹੀ ਡਿਲਿਵਰੀ ਅਟੈਮਪਟ ਨੂੰ ਨਿਸ਼ਾਨਾ ਬਣਾਉ ਅਤੇ ਉਸਨੂੰ ਆਪਣੇ ਸਿਸਟਮ ਵਿੱਚ ਟਰੈਸ ਕਰੋ।

ਸ਼ੁਰੂਆਤ ਵਿੱਚ ਪ੍ਰੋਵਾਈਡਰ ਦਾ ਡਿਲਿਵਰੀ ਆਈਡੈਂਟੀਫਾਇਰ, ਰਿਕਵੇਸਟ ID, ਜਾਂ ਇਵੈਂਟ ID ਲਵੋ। ਇਸ ਇਕ ਮੁੱਲ ਨਾਲ ਤੁਸੀਂ ਮੇਲ ਖਾਣ ਵਾਲੀ ਲੌਗ ਦਰਜਾ ਤੁਰੰਤ ਲੱਭ ਸਕਦੇ ਹੋ।

ਫਿਰ ਤਿੰਨ ਗੱਲਾਂ ਵੇਖੋ:

ਕੀ ਸਿਗਨੇਚਰ ਵੇਰੀਫਿਕੇਸ਼ਨ ਪਾਸ ਹੋਈ?
ਕੀ ਤੁਹਾਡੀ ਟਾਈਮਸਟੈਂਪ ਜਾਂ replay ਵਿਂਡੋ ਚੈੱਕ ਪਾਸ ਹੋਈ (ਜੇ ਤੁਸੀਂ ਵਰਤਦੇ ਹੋ)?
ਕੀ idempotency ਨੇ ਇਸਨੂੰ ਨਵਾਂ ਮੰਨਿਆ ਜਾਂ ਡੁਪਲਿਕੇਟ?

ਫਿਰ ਪੁਸ਼ਟੀ ਕਰੋ ਕਿ ਤੁਸੀਂ ਪ੍ਰੋਵਾਈਡਰ ਨੂੰ ਕੀ ਵਾਪਸ ਕੀਤਾ। ਇੱਕ ਸਲੋ 200 ਵੀ 500 ਜੇਵਾਂ ਨੁਕਸਾਨਦਾਇਕ ਹੋ ਸਕਦਾ ਹੈ ਜੇ ਪ੍ਰੋਵਾਈਡਰ ਟਾਇਮਆਊਟ ਕਰ ਲੈਂਦਾ ਹੈ ਅਤੇ ਰੀਟ੍ਰਾਈ ਕਰਦਾ ਹੈ। ਸਟੇਟਸ ਕੋਡ, ਰਿਸਪਾਂਸ ਸਮਾਂ, ਅਤੇ ਇਹ ਕਿ ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਭਾਰੀ ਕੰਮ ਤੋਂ ਪਹਿਲਾਂ acknowledge ਕੀਤਾ ਕਿ ਨਹੀਂ — ਇਹ ਵੇਖੋ।

ਜੇ ਤੁਸੀਂ ਦੁਹਰਾਉਣਾ ਚਾਹੁੰਦੇ ਹੋ, ਤਾਂ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਕਰੋ: ਇੱਕ redacted raw request sample (ਕੁੰਜੀ ਹੈਡਰਸ ਅਤੇ ਰਾ ਬਾਡੀ) ਸਟੋਰ ਕਰੋ ਅਤੇ ਟੈਸਟ ਵਾਤਾਵਰਨ ਵਿੱਚ ਇੱਕੋ ਸੀਕ੍ਰਿਟ ਅਤੇ ਵੇਰੀਫਿਕੇਸ਼ਨ ਕੋਡ ਵਰਤ ਕੇ replay ਕਰੋ।

10 ਮਿੰਟ ਵਿੱਚ ਚਲਾਉਣ-ਯੋਗ ਛੇਤੀ ਚੈੱਕਲਿਸਟ

ਜਦੋਂ webhook integration "ਰੈਂਡਮਲੀ" fail ਹੋਣ ਲੱਗੇ, ਤੇਜ਼ੀ ਮਹੱਤਵਪੂਰਨ ਹੈ। ਇਹ ਰਨਬੁਕ ਆਮ ਕਾਰਨਾਂ ਨੂੰ ਕੈਚ ਕਰਦਾ ਹੈ।

ਪਹਿਲਾਂ ਇੱਕ ਸਪਸਟ ਉਦਾਹਰਨ ਲਵੋ: ਪ੍ਰੋਵਾਈਡਰ ਦਾ ਨਾਮ, ਇਵੈਂਟ ਕਿਸਮ, ਕਰੀਬੀ ਟਾਈਮਸਟੈਂਪ (ਟਾਈਮਜ਼ੋਨ ਸਮੇਤ), ਅਤੇ ਕੋਈ ਵੀ ਇਵੈਂਟ ID ਜੋ ਗਾਹਕ ਵੇਖ ਸਕਦਾ ਹੈ।

ਫਿਰ ਜਾਂਚ ਕਰੋ:

ਸਿਗਨੇਚਰ verification ਰਾ ਬਾਡੀ ਬਾਇਟਸ (JSON parsing ਤੋਂ ਪਹਿਲਾਂ) ਅਤੇ ਉਸ environment ਲਈ ਸਹੀ ਸੀਕ੍ਰਿਟ ਵਰਤਦਾ ਹੈ।
Replay ਚੈੱਕ ਅਸਲ ਰੀਟ੍ਰਾਈ ਵਤੀਰੇ ਲਈ ਠੀਕ ਹਨ (ਅਤੇ ਤੁਹਾਡਾ ਸਰਵਰ ਘੜੀ ਸਹੀ ਹੈ)।
Idempotency ਵਾਕਈ dedupe ਕਰਦਾ ਹੈ (ਯੂਨੀਕ ਕਨਸਟਰੇਂਟ, ਪ੍ਰੋਸੈਸਿੰਗ ਤੋਂ ਪਹਿਲਾਂ ਲਿਖਿਆ, ਸਮਝਦਾਰ ਰੀਟੇਨ)।
ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਸਿਰਫ਼ ਵੈਰੀਫਿਕੇਸ਼ਨ ਅਤੇ ਡ ਯੂਰਾਬਲ ਰਿਕਾਰਡਿੰਗ/ਕੀਊਇੰਗ ਤੋਂ ਬਾਅਦ acknowledge ਕਰਦਾ ਹੈ।
ਲੌਗ ਇੱਕ ਘੱਟ, searchable receipt ਸ਼ਾਮਿਲ ਕਰਦੇ ਹਨ: provider, event_id, signature_ok, replay_ok, idempotency_status, response_code, latency_ms.

ਜੇ ਪ੍ਰੋਵਾਈਡਰ ਕਹਿੰਦਾ ਹੈ "ਅਸੀਂ 20 ਵਾਰੀ ਰੀਟ੍ਰਾਈ ਕੀਤੀ," ਤਾਂ ਆਮ ਪੈਟਰਨ ਪਹਿਲਾਂ ਚੈਕ ਕਰੋ: ਗਲਤ ਸੀਕ੍ਰਿਟ (signature fails), ਘੜੀ ਡ੍ਰਿਫਟ (replay window), ਪੇਲੋਡ ਸਾਈਜ਼ ਸੀਮਾਵਾਂ (413), ਟਾਈਮਆਊਟ (ਕੋਈ ਜਵਾਬ ਨਹੀਂ), ਅਤੇ ਡਾਊਨਸਟਰੀਮ dependency ਵੱਲੋਂ 5xx ਧੜਾ।

ਉਦਾਹਰਨ: ਇੱਕ “ਗੁੰਮ ਇਵੈਂਟ” ਰਿਪੋਰਟ ਨੂੰ ਐਂਡ-ਟੂ-ਐਂਡ ਟਰੇਸ ਕਰਨਾ

Standardize your webhook pattern

Create a consistent verify-record-queue-respond flow you can reuse across projects.

Generate Code

ਇੱਕ ਗਾਹਕ ਮੈਲ ਕਰਦਾ ਹੈ: “ਅਸੀਂ ਕੱਲ੍ਹ ਇੱਕ invoice.paid ਇਵੈਂਟ ਮਿਸ ਕੀਤਾ। ਸਾਡੀ ਸਿਸਟਮ ਨੇ ਅਪਡੇਟ ਨਹੀਂ ਕੀਤਾ।” ਇਹ ਹੈ ਇੱਕ ਤੇਜ਼ ਟਰੇਸ ਕਰਨ ਦਾ ਤਰੀਕਾ।

ਸਭ ਤੋਂ ਪਹਿਲਾਂ ਪੁਸ਼ਟੀ ਕਰੋ ਕਿ ਪ੍ਰੋਵਾਈਡਰ ਨੇ ਡਿਲਿਵਰੀ ਦੀ ਕੋਸ਼ਿਸ਼ ਕੀਤੀ ਸੀ। ਇਵੈਂਟ ID, ਟਾਈਮਸਟੈਂਪ, ਡੈਸਟਿਨੇਸ਼ਨ URL, ਅਤੇ ਜੋ ਸਤਿਕਾਰਿਤ ਜਵਾਬ ਕੋਡ ਤੁਹਾਡੀ ਐਂਡਪੌਇੰਟ ਨੇ ਵਾਪਸ ਕੀਤਾ — ਇਹ ਲਵੋ। ਜੇ ਰੀਟ੍ਰਾਈ ਹੋਈਆਂ, ਤਾਂ ਪਹਿਲੀ ਫੇਲ ਦਾ ਕਾਰਨ ਨੋਟ ਕਰੋ ਅਤੇ ਦੇਖੋ ਕਿ ਕੀ ਬਾਅਦ ਦੀ ਰੀਟ੍ਰਾਈ ਸਫਲ ਹੋਈ।

ਅਗਲੀ, ਏਜ 'ਤੇ ਤੁਹਾਡਾ ਕੋਡ ਕੀ ਦੇਖਿਆ ਉਸਦੀ ਪੁਸ਼ਟੀ ਕਰੋ: ਉਸ ਐਂਡਪੌਇੰਟ ਲਈ ਸਕ੍ਰਿਟ ਕਾਂਫਿਗ ਦਿਖੋ, ਰਾ ਰਿਕਵੇਸਟ ਬਾਡੀ ਨਾਲ ਸਿਗਨੇਚਰ verification ਫਿਰੋਂ ਕੈਲਕੁਲੇਟ ਕਰੋ, ਅਤੇ ਪ੍ਰਾਪਤ ਟਾਈਮਸਟੈਂਪ ਨੂੰ ਤੁਹਾਡੇ ਅਨੁਮਤ ਵਿੰਡੋ ਨਾਲ ਚੈੱਕ ਕਰੋ।

ਰੀਟ੍ਰਾਈ ਵਿੰਡੋਜ਼ ਨਾਲ ਸਾਵਧਾਨ ਰਹੋ। ਜੇ ਤੁਹਾਡੀ ਵਿੰਡੋ 5 ਮਿੰਟ ਹੈ ਅਤੇ ਪ੍ਰੋਵਾਈਡਰ 30 ਮਿੰਟ ਬਾਅਦ ਰੀਟ੍ਰਾਈ ਕਰਦਾ ਹੈ, ਤੁਸੀਂ ਇੱਕ ਵਾਜਬੀ ਰੀਟ੍ਰਾਈ ਨੂੰ ਰੱਦ ਕਰ ਸਕਦੇ ਹੋ। ਜੇ ਇਹ ਤੁਹਾਡੀ ਨੀਤੀ ਹੈ, ਤਾਂ ਇਹ ਦਸਤਾਵੇਜ਼ੀ ਹੋਵੇ। ਨਹੀਂ ਤਾਂ ਵਿੰਡੋ ਵਧਾਉ ਜਾਂ ਲਾਜ਼ਮੀ ਤੌਰ 'ਤੇ idempotency ਨੂੰ ਪ੍ਰਧਾਨ ਸੁਰੱਖਿਆ ਬਣਾਓ।

ਜੇ ਸਿਗਨੇਚਰ ਅਤੇ ਟਾਈਮਸਟੈਂਪ ਠੀਕ ਹਨ, ਤਾਂ ਇਵੈਂਟ ID ਨੂੰ ਆਪਣੇ ਸਿਸਟਮ ਵਿੱਚ ਫੋਲੋ ਕਰੋ ਅਤੇ ਸਵਾਲ ਪੁੱਛੋ: ਕੀ ਤੁਸੀਂ ਇਸਨੂੰ ਪ੍ਰੋਸੈਸ ਕੀਤਾ, ਡੀਡਿਊਪ ਕੀਤਾ, ਜਾਂ ਡਰਾਪ ਕੀਤਾ?

ਆਮ ਨਤੀਜੇ:

Deduped: idempotency key ਪਹਿਲਾਂ ਹੀ ਮੌਜੂਦ ਹੈ, ਇਸ ਲਈ ਤੁਸੀਂ 200 ਵਾਪਸ ਕੀਤਾ ਬਿਨਾਂ ਕਾਰੋਬਾਰੀ ਲੋਜਿਕ ਨੂੰ ਦੁਹਰਾਏ।
Rejected: validation ਫੇਲ (signature mismatch, timestamp too old, missing headers)।
Timed out: ਹੈਂਡਲਰ ਨੇ ਬਹੁਤ ਸਮਾਂ ਲਿਆ, ਪ੍ਰੋਵਾਈਡਰ ਨੇ ਇਸਨੂੰ ਫੇਲ ਕਰਾਰ ਦਿੱਤਾ, ਫਿਰ ਰੀਟ੍ਰਾਈ ਕੀਤਾ।

ਜਦੋਂ ਤੁਸੀਂ ਗਾਹਕ ਨੂੰ ਜਵਾਬ ਦਿਓ, ਸਫ਼ ਅਤੇ ਨਿਰਧਾਰਤ ਹੋਵੋ: “ਅਸੀਂ 10:03 ਅਤੇ 10:33 UTC 'ਤੇ ਡਿਲਿਵਰੀ ਅਟੈਮਪਟ ਪ੍ਰਾਪਤ ਕੀਤੇ। ਪਹਿਲਾ 10s ਬਾਅਦ ਟਾਈਮਆਊਟ ਹੋਇਆ; ਰੀਟ੍ਰਾਈ 5 ਮਿੰਟ ਦੀ ਵਿੰਡੋ ਤੋਂ ਬਾਹਰ ਸੀ ਇਸ ਲਈ ਰੱਦ ਹੋ ਗਿਆ। ਅਸੀਂ ਵਿੰਡੋ ਵਧਾ ਦਿੱਤੀ ਅਤੇ ਤੇਜ਼ ਐਕਨੌਲੈਜਮੈਂਟ ਜੋੜਿਆ। ਜੇ ਲੋੜ ਹੋਵੇ ਤਾਂ ਇਵੈਂਟ ID X ਮੁੜ ਭੇਜੋ।”

ਅਗਲੇ ਕਦਮ: ਇਸਨੂੰ ਦੁਹਰਾਉਣਯੋਗ ਬਣਾਓ

Webhook fires ਨੂੰ ਰੋਕਣ ਦਾ ਸਭ ਤੋਂ ਤੇਜ਼ ਤਰੀਕਾ ਇਹ ਹੈ ਕਿ ਹਰ ਇਕ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਇੱਕੋ playbook ਨੂੰ ਫੋਲੋ ਕਰੇ। ਉਹ ਸੰਬੰਧ ਲਿਖ ਕੇ ਰੱਖੋ ਜੋ ਤੁਸੀਂ ਅਤੇ ਸੈਂਡਰ ਸਹਿਮਤ ਹੋ: ਲਾਜ਼ਮੀ ਹੈਡਰ, ਸਹੀ ਸਾਇਨਿੰਗ ਵਿਧੀ, ਕਿਹੜਾ ਟਾਈਮਸਟੈਂਪ ਵਰਤਿਆ ਜਾਵੇ, ਅਤੇ ਕਿਹੜੀਆਂ IDs ਤੁਸੀਂ ਯੂਨੀਕ ਮੰਨਦੇ ਹੋ।

ਫਿਰ ਹਰ ਡਿਲਿਵਰੀ ਅਟੈਮਪਟ ਲਈ ਜੋ ਤੁਸੀਂ ਰਿਕਾਰਡ ਕਰੋ ਉਹ ਸਟੈਂਡਰਡ ਕਰੋ। ਛੋਟੀ receipt log ਆਮ ਤੌਰ 'ਤੇ ਕਾਫ਼ੀ ਹੁੰਦੀ ਹੈ: received_at, event_id, delivery_id, signature_valid, idempotency_result (new/duplicate), handler_version, ਅਤੇ response status।

ਇਕ workflow ਜੋ ਵਧਣ ਨਾਲ ਵੀ ਲਾਗੂ ਰਹੇ:

ਇੱਕ dedicated test endpoint ਰੱਖੋ ਜੋ ਸਿਗਨੇਚਰ verify ਕਰਦਾ ਅਤੇ 2xx ਰਿਟਰਨ ਕਰਦਾ ਹੈ ਬਿਨਾਂ ਬਿਜ਼ਨਸ ਕਾਰਵਾਈ ਚਲਾਏ।
ਰਾ ਰਿਕਵੇਸਟ ਬਾਡੀ ਅਤੇ ਕੁਝ ਮੁੱਖ ਹੈਡਰਾਂ ਨੂੰ ਥੋੜ੍ਹੇ ਸਮੇਂ ਲਈ ਸਟੋਰ ਕਰੋ, ਸਿਰਫ ਡੀਬੱਗ ਅਤੇ ਰੀਪਲੇ ਲਈ।
ਇੱਕ replay-safe reprocess job ਬਣਾਓ ਜੋ ਸਟੋਰ ਕੀਤੇ ਇਵੈਂਟਸ ਨੂੰ ਇੱਕੋ ਹੀ ਹੈਂਡਲਰ ਕੋਡ ਰਾਹੀਂ ਦੁਬਾਰਾ ਚਲਾਉਂਦਾ ਹੈ।
ਇੱਕ ਅੰਦਰੂਨੀ ਚੈੱਕਲਿਸਟ ਰੱਖੋ ਜੋ support, QA, ਅਤੇ engineering ਸਭ ਫੋਲੋ ਕਰਨ।

ਜੇ ਤੁਸੀਂ Koder.ai (koder.ai) ਤੇ ਐਪ ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ Planning Mode webhook contract ਪਹਿਲਾਂ define ਕਰਨ ਦਾ ਵਧੀਆ ਤਰੀਕਾ ਹੈ (headers, signing, IDs, retry behavior) ਅਤੇ ਫਿਰ consistent endpoint ਅਤੇ receipt record ਹਰ ਪ੍ਰੋਜੈਕਟ ਵਿੱਚ ਜਨਰੇਟ ਕਰੋ। ਇਹ ਸਥਿਰਤਾ ਹੈ ਜੋ ਡੀਬੱਗਿੰਗ ਨੂੰ ਹੀਰੋਇਕ ਨਹੀਂ, ਤੇਜ਼ ਬਣਾਉਂਦੀ ਹੈ।

ਅਕਸਰ ਪੁੱਛੇ ਜਾਣ ਵਾਲੇ ਸਵਾਲ

Why do webhooks seem to “randomly” fail or duplicate in production?

Because webhook delivery is usually at-least-once, not exactly once. Providers retry on timeouts, 5xx responses, and sometimes when they don’t see your 2xx in time, so you can get duplicates, delays, and out-of-order deliveries even when everything is “working.”

What’s the safest basic flow for handling a webhook request?

Default to this rule: verify the signature first, then store/dedupe the event, then respond 2xx, then do heavy work asynchronously.

If you do heavy work before replying, you’ll hit timeouts and trigger retries; if you reply before recording anything, you can lose events on crashes.

How do I avoid signature mismatches when verifying webhooks?

Use the raw request body bytes exactly as received. Don’t parse JSON and re-serialize before verification—whitespace, key order, and number formatting changes can break signatures.

Also make sure you’re recreating the provider’s signed payload precisely (often timestamp + "." + raw_body).

What should my endpoint do when signature verification fails?

Return a 4xx (commonly 400 or 401) and do not process the payload.

Log a minimal reason (missing signature header, mismatch, bad timestamp window), but don’t log secrets or full sensitive payloads.

What is an idempotency key for webhooks, and which value should I use?

An idempotency key is a stable unique identifier you store so retries don’t re-apply side effects.

Best options:

Event ID (ideal when one event maps to one business change)
Delivery/message ID (if it stays constant across retries)
Hash of stable fields (last resort)

Enforce it with a so only one request wins under concurrency.

How do I dedupe webhooks without race conditions?

Write the idempotency key before doing side effects, with a uniqueness rule. Then either:

Mark it processed after success, or
Record a failure status so you can retry safely

If the insert fails because the key already exists, return 2xx and skip the business action.

How do I add replay protection without rejecting legitimate retries?

Use a timestamp in the signed data and reject requests outside a short window (for example, a few minutes).

To avoid blocking legitimate retries:

Allow some clock drift
Log your server time and received timestamp on rejection
Treat idempotency as the main protection against duplicates; the time window is mainly to stop late replays

How should I handle out-of-order webhook events?

Don’t assume delivery order equals event order. Make handlers tolerant:

Use upserts where possible
Check current state before applying changes
If an object isn’t found, consider retrying later (via a queue) instead of permanently failing

Store the event ID and type so you can reason about what happened even when order is weird.

What should I log so webhook debugging doesn’t turn into guessing?

Log a small “receipt” per delivery attempt so you can trace one event end-to-end:

provider, event_id, delivery_id
signature_ok, replay_ok
idempotency result (new/duplicate)
response_code, latency_ms
timestamps (received/first_seen/last_seen)

Keep logs searchable by event ID so support can answer customer reports quickly.

What’s a fast way to investigate a customer report that “a webhook never arrived”?

Start by asking for a single concrete identifier: event ID or delivery ID, plus an approximate timestamp.

Then check in this order:

Signature verification result
Timestamp/replay window result (if used)
Idempotency outcome (new vs duplicate)
What you returned (status code + latency)

If you build endpoints using Koder.ai, keep the handler pattern consistent across projects (verify → record/dedupe → queue → respond). Consistency makes these checks fast when incidents happen.