L’indice della pagina

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>The table of contents rail</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fontsource-variable/schibsted-grotesk@5.3.0/index.css">
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div class="layout" data-layout>
    <!-- the table of contents: on a wide screen a column on the right that stays put, on a phone a bar at the top
         that opens it. The rail beside the entries is an SVG path drawn from where the entries are; its lit stretch
         covers the sections on screen -->
    <aside class="toc" data-toc>
      <button class="toc__bar" type="button" aria-expanded="false" aria-controls="toc-panel" data-bar>
        <svg class="toc__ring" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="9" pathLength="1" data-ring/></svg>
        <span class="toc__bar-words"><span class="toc__bar-label">On this page</span><span class="toc__bar-now" data-now>Overview</span></span>
        <svg class="toc__chevron" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg>
      </button>
      <div class="toc__panel" id="toc-panel" data-panel>
        <p class="toc__title" id="toc-title">On this page</p>
        <nav class="toc__nav" aria-labelledby="toc-title">
          <svg class="rail" aria-hidden="true" data-rail>
            <path class="rail__track" data-track/>
            <path class="rail__read" data-read/>
            <path class="rail__ghost" data-ghost/>
            <path class="rail__halo" data-halo/>
            <path class="rail__lit" data-lit/>
            <circle class="rail__head" r="3.5" data-head/>
          </svg>
          <ol class="toc__list" data-list>
            <li><a href="#overview" data-depth="2">Overview</a></li>
            <li><a href="#how-signing-works" data-depth="2">How signing works</a></li>
            <li><a href="#the-signature-header" data-depth="3">The signature header</a></li>
            <li><a href="#rotating-the-secret" data-depth="3">Rotating the secret</a></li>
            <li><a href="#two-secrets-at-once" data-depth="4">Two secrets at once</a></li>
            <li><a href="#verify-a-request" data-depth="2">Verify a request</a></li>
            <li><a href="#with-the-sdk" data-depth="3">With the SDK</a></li>
            <li><a href="#by-hand" data-depth="3">By hand</a></li>
            <li><a href="#retries-and-replays" data-depth="2">Retries and replays</a></li>
            <li><a href="#the-retry-schedule" data-depth="3">The retry schedule</a></li>
            <li><a href="#rejecting-old-events" data-depth="3">Rejecting old events</a></li>
            <li><a href="#test-locally" data-depth="2">Test locally</a></li>
            <li><a href="#going-live" data-depth="2">Going live</a></li>
          </ol>
        </nav>
        <div class="toc__foot">
          <span class="toc__left" data-left>3 min read</span>
          <button class="toc__up" type="button" data-up>
            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 13V3M4 7l4-4 4 4"/></svg>
            Back to top
          </button>
        </div>
      </div>
    </aside>

    <!-- the article it indexes: plain headings and short paragraphs, only there to be read and scrolled -->
    <main class="doc" data-doc>
      <h2 id="overview" tabindex="-1">Overview</h2>
      <p>A webhook endpoint is a public URL. Anyone who finds it can send it a request that looks exactly like a real event, and if your code acts on it, a stranger can mark orders as paid or cancel bookings.</p>
      <p>A signature on every event closes that door: your code repeats the sender’s computation and acts only when the two results match.</p>

      <h2 id="how-signing-works" tabindex="-1">How signing works</h2>
      <p>Each endpoint has its own signing secret, shown once when the endpoint is created. The secret never travels with the events: only what it produces does.</p>
      <p>A signature covers the moment the event was sent and its body, so a request captured on the way cannot be replayed hours later.</p>

      <h3 id="the-signature-header" tabindex="-1">The signature header</h3>
      <p>Every event carries a header with a timestamp and one or more signatures, separated by commas. Each signature is an HMAC-SHA256 of the timestamp, a full stop and the raw body.</p>

      <h3 id="rotating-the-secret" tabindex="-1">Rotating the secret</h3>
      <p>Rotate a secret when someone who knew it leaves the team, when it may have been logged by accident, or simply once a year, and choose how long the old one keeps working.</p>

      <h4 id="two-secrets-at-once" tabindex="-1">Two secrets at once</h4>
      <p>While both secrets are valid, every event is signed with each of them. Code that accepts any of the signatures keeps working through the change, without a single rejected event.</p>

      <h2 id="verify-a-request" tabindex="-1">Verify a request</h2>
      <p>Verification comes before anything else in your handler: before parsing, before logging the body, before touching the database. Anything that fails gets an error and no further work.</p>

      <h3 id="with-the-sdk" tabindex="-1">With the SDK</h3>
      <p>The official libraries do the whole check in one call, including the tolerance on the timestamp and the secrets in rotation, and throw an error when it fails.</p>

      <h3 id="by-hand" tabindex="-1">By hand</h3>
      <p>Without a library the check is short enough to write yourself. Compare the signatures in constant time, and check every one in the header, not just the first.</p>

      <h2 id="retries-and-replays" tabindex="-1">Retries and replays</h2>
      <p>An event counts as delivered when your endpoint answers with a success status within ten seconds. Anything else, a timeout included, is a failure, and the event is sent again later.</p>

      <h3 id="the-retry-schedule" tabindex="-1">The retry schedule</h3>
      <p>Failed events are tried again seven times over about a day and a half, waiting longer each time. Each new attempt is signed again with a fresh timestamp.</p>

      <h3 id="rejecting-old-events" tabindex="-1">Rejecting old events</h3>
      <p>Reject events whose timestamp is more than five minutes away from your server’s clock: a request recorded on the way is then useless almost as soon as it is captured.</p>

      <h2 id="test-locally" tabindex="-1">Test locally</h2>
      <p>The command line tool forwards real, signed events to a URL on your own machine, with a temporary secret for the session, so a failed check shows up at once.</p>

      <h2 id="going-live" tabindex="-1">Going live</h2>
      <p>Before switching to live mode, make sure the raw body is verified first, the live secret sits in your secret manager, old events are rejected and slow work goes to a queue.</p>
      <p>From then on your endpoint acts only on events that are genuine.</p>
    </main>
  </div>

  <script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js"></script>
  <script src="script.js"></script>
</body>
</html>