docs: add idempotent webhook delivery pattern

[asllanmaciel]

O que muda

• adiciona um guia prático de idempotência usando X-GitHub-Delivery
• documenta o fluxo atômico claim → process → complete/fail
• cobre concorrência, leases, fencing token e recuperação de worker interrompido
• explica a janela entre efeito externo e marcação de completed
• compara trade-offs entre banco relacional, Redis e filas
• inclui TTL, retry/backoff e observabilidade sem payloads/secrets
• conecta o material ao checklist principal do README

O conteúdo foi alinhado à documentação oficial atual do GitHub: redeliveries mantêm o mesmo X-GitHub-Delivery, o endpoint deve responder 2xx em até 10 segundos e falhas não são redeliveradas automaticamente pelo GitHub.

Closes #3

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8e94d08d2a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make the inbox claim and queue publication atomic

If the endpoint crashes or queue publication fails after tryClaim succeeds but before this enqueue completes, the durable record remains processing while no job exists to process it. Because the guide also notes that GitHub does not automatically redeliver failures and specifies no inbox dispatcher or reaper, the delivery can be lost indefinitely; persist an outbox/job atomically with the claim and dispatch it separately, or otherwise provide an explicit recovery mechanism.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reacquire the claim before retrying a failed job

When a domain operation raises a transient error, this changes the inbox status to failed and then asks the queue to retry the same job. On the next invocation, ownsClaim will reject that job because it no longer owns a processing reservation, so it returns without retrying the operation; the retry path must atomically transition the retryable failure back to processing and obtain a valid token, or retain the claim while queue-managed retries remain.

Useful? React with 👍 / 👎.