<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: mmiura</title>
    <description>The latest articles on DEV Community by mmiura (@mmiura_shannon).</description>
    <link>https://dev.to/mmiura_shannon</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4146522%2F8a12be19-da74-4c63-91f1-7a0ffb289dcd.jpg</url>
      <title>DEV Community: mmiura</title>
      <link>https://dev.to/mmiura_shannon</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/mmiura_shannon"/>
    <language>en</language>
    <item>
      <title>Getting the Raw Request Body for Webhook Verification in 8 Frameworks</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Sat, 14 Nov 2026 13:17:33 +0000</pubDate>
      <link>https://dev.to/shannonllc/getting-the-raw-request-body-for-webhook-verification-in-8-frameworks-2pnd</link>
      <guid>https://dev.to/shannonllc/getting-the-raw-request-body-for-webhook-verification-in-8-frameworks-2pnd</guid>
      <description>&lt;p&gt;Most signature mismatches come from the framework parsing the JSON before you verify it. We show how to read the raw request body and verify a webhook in Express, Next.js, Hono, FastAPI, Django, Rails, Laravel and Go.&lt;/p&gt;

&lt;p&gt;A webhook signature is computed over the bytes the sender put on the wire. Parse the JSON and serialize it again and you change whitespace, key order or how numbers and Unicode are written, and the signature no longer matches. The fix is always the same: read the body of the webhook route before any JSON parser runs. This post shows how in eight frameworks, with minimal verification code for each.&lt;/p&gt;

&lt;p&gt;The examples use the &lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks&lt;/a&gt; format that Webhook Admin sends (&lt;code&gt;webhook-id&lt;/code&gt;, &lt;code&gt;webhook-timestamp&lt;/code&gt;, &lt;code&gt;webhook-signature&lt;/code&gt;). Node examples verify with the &lt;code&gt;webhookadmin&lt;/code&gt; npm package; Python, Ruby and Go use the official Standard Webhooks libraries; PHP uses built-in functions. Reading the raw body works the same way for Stripe, GitHub or anyone else. Framework behavior was checked against official docs on 2026-09-27.&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick reference
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Framework&lt;/th&gt;
&lt;th&gt;Raw body&lt;/th&gt;
&lt;th&gt;Type&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Express&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;req.body&lt;/code&gt; on a route with &lt;code&gt;express.raw()&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Buffer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Next.js (App Router)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;await request.text()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;string&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Next.js (Pages Router)&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;bodyParser: false&lt;/code&gt;, read the stream&lt;/td&gt;
&lt;td&gt;Buffer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hono&lt;/td&gt;
&lt;td&gt;&lt;code&gt;await c.req.text()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;string&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;FastAPI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;await request.body()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;bytes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Django&lt;/td&gt;
&lt;td&gt;&lt;code&gt;request.body&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;bytes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rails&lt;/td&gt;
&lt;td&gt;&lt;code&gt;request.raw_post&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;String&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Laravel&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$request-&amp;gt;getContent()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;string&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Go (net/http)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;io.ReadAll(r.Body)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;[]byte&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What changes when a body is re-serialized
&lt;/h2&gt;

&lt;p&gt;Take &lt;code&gt;{"amount": 1.50, "name": "caf\u00e9"}&lt;/code&gt;. After &lt;code&gt;JSON.parse&lt;/code&gt; and &lt;code&gt;JSON.stringify&lt;/code&gt; in JavaScript you get &lt;code&gt;{"amount":1.5,"name":"café"}&lt;/code&gt;: the spaces are gone, &lt;code&gt;1.50&lt;/code&gt; became &lt;code&gt;1.5&lt;/code&gt;, and the escaped &lt;code&gt;\u00e9&lt;/code&gt; became a literal &lt;code&gt;é&lt;/code&gt;, which is two bytes in UTF-8 instead of six. Python's &lt;code&gt;json.dumps&lt;/code&gt; produces yet another variant, with spaces after the separators and non-ASCII characters escaped by default. The data is identical; the bytes, and so the HMAC, are not. No amount of careful re-serialization reliably reproduces the sender's bytes, which is why every example below reads the body before anything parses it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Express
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://github.com/expressjs/body-parser" rel="noopener noreferrer"&gt;body-parser&lt;/a&gt;'s &lt;code&gt;raw&lt;/code&gt; parser puts the body in &lt;code&gt;req.body&lt;/code&gt; as a Buffer. Its &lt;code&gt;type&lt;/code&gt; option defaults to &lt;code&gt;application/octet-stream&lt;/code&gt;, so set it to &lt;code&gt;application/json&lt;/code&gt;; &lt;code&gt;limit&lt;/code&gt; defaults to 100kb.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;express&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'express'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Register the webhook route before express.json()&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/webhooks'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'application/json'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'1mb'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;use&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// for every other route&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If &lt;code&gt;app.use(express.json())&lt;/code&gt; comes first, it parses the webhook route's body too. Stripe's troubleshooting guide gives the same advice about ordering.&lt;/p&gt;

&lt;h2&gt;
  
  
  Next.js (App Router)
&lt;/h2&gt;

&lt;p&gt;Route Handlers receive a standard Web &lt;code&gt;Request&lt;/code&gt;, so &lt;code&gt;request.text()&lt;/code&gt; gives you the body as a string. The Next.js docs use this in their webhook example and note that, unlike API Routes in the Pages Router, no bodyParser configuration is needed (&lt;a href="https://nextjs.org/docs/app/api-reference/file-conventions/route" rel="noopener noreferrer"&gt;route.js&lt;/a&gt;).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/webhooks/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;204&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'invalid signature'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Calling &lt;code&gt;request.json()&lt;/code&gt; first consumes the body, and you can't read it again from the same &lt;code&gt;Request&lt;/code&gt;. Parse after verification, from &lt;code&gt;body&lt;/code&gt; or from what &lt;code&gt;verify&lt;/code&gt; returns.&lt;/p&gt;

&lt;h2&gt;
  
  
  Next.js (Pages Router)
&lt;/h2&gt;

&lt;p&gt;API Routes parse the body automatically. The Next.js docs mention verifying a webhook's raw body as the reason to set &lt;code&gt;bodyParser&lt;/code&gt; to &lt;code&gt;false&lt;/code&gt; (&lt;a href="https://nextjs.org/docs/pages/building-your-application/routing/api-routes" rel="noopener noreferrer"&gt;API Routes&lt;/a&gt;).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// pages/api/webhooks.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;NextApiRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NextApiResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'next'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;config&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;bodyParser&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;readRaw&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextApiRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Buffer&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;chunk&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;chunk&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'string'&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nc"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;concat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;handler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextApiRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextApiResponse&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;readRaw&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Hono
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;c.req.text()&lt;/code&gt; returns the body as a string and &lt;code&gt;c.req.arrayBuffer()&lt;/code&gt; as an ArrayBuffer (&lt;a href="https://hono.dev/docs/api/request" rel="noopener noreferrer"&gt;HonoRequest&lt;/a&gt;). The code is the same on Cloudflare Workers, Bun, Deno and Node.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Hono&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'hono'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Hono&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Bindings&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/webhooks'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// on Workers, secrets come from c.env&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;body&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'invalid signature'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Don't attach a validator that reads the body (such as &lt;code&gt;zValidator('json', …)&lt;/code&gt;) to the webhook route ahead of verification.&lt;/p&gt;

&lt;h2&gt;
  
  
  FastAPI
&lt;/h2&gt;

&lt;p&gt;FastAPI's &lt;code&gt;Request&lt;/code&gt; is Starlette's, and &lt;code&gt;await request.body()&lt;/code&gt; returns bytes (&lt;a href="https://fastapi.tiangolo.com/advanced/using-request-directly/" rel="noopener noreferrer"&gt;FastAPI docs&lt;/a&gt;). If you declare the body as a Pydantic model parameter, you only ever see the parsed value.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;fastapi&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;standardwebhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webhooks&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;

&lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"WEBHOOK_SECRET"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;# whsec_…&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="nd"&gt;@app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/webhooks"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;body&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;# bytes&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;dict&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;except&lt;/span&gt; &lt;span class="nc"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Django
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;HttpRequest.body&lt;/code&gt; is "the raw HTTP request body as a bytestring" (&lt;a href="https://docs.djangoproject.com/en/stable/ref/request-response/" rel="noopener noreferrer"&gt;Django docs&lt;/a&gt;). If something reads the request stream first with &lt;code&gt;request.read()&lt;/code&gt;, accessing &lt;code&gt;request.body&lt;/code&gt; afterwards raises &lt;code&gt;RawPostDataException&lt;/code&gt;. Exempt the webhook view from CSRF checks.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;django&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;http&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;HttpResponse&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;django&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;views&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;decorators&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;csrf&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;csrf_exempt&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;django&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;views&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;decorators&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;http&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;require_POST&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;standardwebhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webhooks&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;

&lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"WEBHOOK_SECRET"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="nd"&gt;@csrf_exempt&lt;/span&gt;
&lt;span class="nd"&gt;@require_POST&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;dict&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;except&lt;/span&gt; &lt;span class="nc"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;HttpResponse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;HttpResponse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Rails
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;request.raw_post&lt;/code&gt; returns the body as a string (&lt;a href="https://api.rubyonrails.org/classes/ActionDispatch/Request.html" rel="noopener noreferrer"&gt;ActionDispatch::Request&lt;/a&gt;), and the Standard Webhooks Ruby library's README passes exactly that in its Rails example. In controllers that inherit from &lt;code&gt;ActionController::Base&lt;/code&gt;, exclude the webhook action from forgery protection.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;WebhooksController&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ApplicationController&lt;/span&gt;
  &lt;span class="n"&gt;protect_from_forgery&lt;/span&gt; &lt;span class="n"&gt;except&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="ss"&gt;:create&lt;/span&gt;

  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;
    &lt;span class="n"&gt;webhook&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;StandardWebhooks&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;ENV&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'WEBHOOK_SECRET'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;payload&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;webhook&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;raw_post&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="s1"&gt;'webhook-id'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'webhook-id'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="s1"&gt;'webhook-timestamp'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'webhook-timestamp'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="s1"&gt;'webhook-signature'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'webhook-signature'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;head&lt;/span&gt; &lt;span class="ss"&gt;:no_content&lt;/span&gt;
  &lt;span class="k"&gt;rescue&lt;/span&gt; &lt;span class="nc"&gt;StandardWebhooks&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;WebhookVerificationError&lt;/span&gt;
    &lt;span class="n"&gt;head&lt;/span&gt; &lt;span class="ss"&gt;:bad_request&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Laravel
&lt;/h2&gt;

&lt;p&gt;Laravel's &lt;code&gt;Request&lt;/code&gt; extends Symfony's, whose &lt;code&gt;getContent()&lt;/code&gt; returns the raw body (&lt;a href="https://symfony.com/doc/current/components/http_foundation.html" rel="noopener noreferrer"&gt;Symfony HttpFoundation&lt;/a&gt;). Exclude the route from CSRF checks with &lt;code&gt;validateCsrfTokens(except: [...])&lt;/code&gt; in &lt;code&gt;bootstrap/app.php&lt;/code&gt;; Laravel's own docs use Stripe webhooks as the example (&lt;a href="https://laravel.com/docs/12.x/csrf" rel="noopener noreferrer"&gt;Laravel CSRF&lt;/a&gt;).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;use&lt;/span&gt; &lt;span class="nc"&gt;Illuminate&lt;/span&gt;\&lt;span class="nc"&gt;Http&lt;/span&gt;\&lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nc"&gt;Route&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/webhooks'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Request&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nv"&gt;$body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;getContent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nv"&gt;$id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'webhook-id'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nv"&gt;$ts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'webhook-timestamp'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nf"&gt;ctype_digit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$ts&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nf"&gt;abs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;time&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nv"&gt;$ts&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;300&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nv"&gt;$key&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;base64_decode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;substr&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;env&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'WEBHOOK_SECRET'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;strlen&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'whsec_'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nv"&gt;$expected&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;base64_encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;hash_hmac&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'sha256'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"{$id}.{$ts}.{$body}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;explode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;' '&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'webhook-signature'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nv"&gt;$part&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;$version&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$sig&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;array_pad&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;explode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;','&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$part&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$version&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'v1'&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nf"&gt;hash_equals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$expected&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$sig&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Go (net/http)
&lt;/h2&gt;

&lt;p&gt;For server requests &lt;code&gt;r.Body&lt;/code&gt; is always non-nil and returns EOF immediately when there's no body. Wrap it in &lt;code&gt;http.MaxBytesReader&lt;/code&gt; so an oversized body can't eat memory (&lt;a href="https://pkg.go.dev/net/http" rel="noopener noreferrer"&gt;net/http&lt;/a&gt;).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight go"&gt;&lt;code&gt;&lt;span class="k"&gt;package&lt;/span&gt; &lt;span class="n"&gt;main&lt;/span&gt;

&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="s2"&gt;"io"&lt;/span&gt;
    &lt;span class="s2"&gt;"net/http"&lt;/span&gt;
    &lt;span class="s2"&gt;"os"&lt;/span&gt;

    &lt;span class="n"&gt;standardwebhooks&lt;/span&gt; &lt;span class="s2"&gt;"github.com/standard-webhooks/standard-webhooks/libraries/go"&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="k"&gt;func&lt;/span&gt; &lt;span class="nf"&gt;main&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="n"&gt;standardwebhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NewWebhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Getenv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"WEBHOOK_SECRET"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="kc"&gt;nil&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nb"&gt;panic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;HandleFunc&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"POST /webhooks"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;func&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ResponseWriter&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="n"&gt;io&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ReadAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxBytesReader&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="kc"&gt;nil&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"too large"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;StatusRequestEntityTooLarge&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Header&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="kc"&gt;nil&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"invalid signature"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;StatusBadRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WriteHeader&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;StatusNoContent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ListenAndServe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;":3000"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;nil&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Common pitfalls
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A global JSON parser.&lt;/strong&gt; Express's &lt;code&gt;app.use(express.json())&lt;/code&gt;, NestJS defaults, Hono or FastAPI validators - anything that reads the body before your route means the raw bytes are gone. In NestJS, start the app with &lt;code&gt;NestFactory.create(AppModule, { rawBody: true })&lt;/code&gt; and read &lt;code&gt;req.rawBody&lt;/code&gt; (&lt;a href="https://docs.nestjs.com/faq/raw-body" rel="noopener noreferrer"&gt;NestJS docs&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Changing the body while converting it to a string.&lt;/strong&gt; Decoding as something other than UTF-8, normalizing line endings or trimming whitespace all break the signature. Pass bytes, or decode as UTF-8 and leave it alone.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;CSRF protection.&lt;/strong&gt; Rails, Django and Laravel require CSRF tokens on POSTs to protect forms. Webhook senders can't send one, so exempt the webhook route only. Stripe's docs carry the same warning.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Checking your setup
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Before verifying, log the body's length and SHA-256.&lt;/li&gt;
&lt;li&gt;Compute the SHA-256 of what was sent, from the sender's delivery log or your own test script.&lt;/li&gt;
&lt;li&gt;If they match, you have the raw body. If not, something is transforming it.&lt;/li&gt;
&lt;li&gt;If the bodies match but verification still fails, the secret or the signed content is wrong. &lt;a href="https://webhookadmin.com/en/blog/webhook-signature-verification-failed/" rel="noopener noreferrer"&gt;Why webhook signature verification fails&lt;/a&gt; walks through that.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;To send signed test payloads to a local handler, see &lt;a href="https://webhookadmin.com/en/blog/test-webhooks-locally/" rel="noopener noreferrer"&gt;testing webhooks locally&lt;/a&gt;. Webhook Admin's signature format and libraries for other languages are in &lt;a href="https://webhookadmin.com/en/docs/sdk/#libraries" rel="noopener noreferrer"&gt;signature verification&lt;/a&gt; and the &lt;a href="https://webhookadmin.com/en/docs/#verify" rel="noopener noreferrer"&gt;verify step of getting started&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you want to send webhooks that receivers can verify with an official library in any language, you can try Webhook Admin for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;How do I get the raw body in the Next.js App Router?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Call await request.text() in the Route Handler. The Next.js docs use exactly that in their webhook example and note that, unlike the Pages Router, no bodyParser configuration is needed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How do I use a raw body for just one Express route?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Give that route express.raw({ type: 'application/json' }) as its middleware and register app.use(express.json()) after it. req.body is then a Buffer you can pass straight to your verification function.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;In Python, should I pass bytes or str to the verifier?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Pass the bytes you received. FastAPI's await request.body() and Django's request.body both return bytes, and the Standard Webhooks Python library decodes bytes as UTF-8 itself.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Which framework gave you the most trouble getting the raw body? Let us know in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/webhook-raw-body-by-framework/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>node</category>
      <category>python</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Send Your First Webhook with Webhook Admin (Node.js)</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Thu, 12 Nov 2026 13:17:31 +0000</pubDate>
      <link>https://dev.to/shannonllc/send-your-first-webhook-with-webhook-admin-nodejs-5cb9</link>
      <guid>https://dev.to/shannonllc/send-your-first-webhook-with-webhook-admin-nodejs-5cb9</guid>
      <description>&lt;p&gt;This is the shortest path from signing up to a signed webhook arriving at your endpoint. In Node.js with the webhookadmin package, the sending side is about 20 lines, and we also show the same call without the SDK.&lt;/p&gt;

&lt;p&gt;Getting your first webhook out of Webhook Admin takes five steps: sign up, create a project, create an API key, register a consumer and an endpoint, and send. In Node.js with the &lt;code&gt;webhookadmin&lt;/code&gt; package, the sending side - creating the consumer and endpoint, sending, and checking the delivery - is about 20 lines. This post walks through each step, shows the same call without the SDK, and ends with signature verification on the receiving side.&lt;/p&gt;

&lt;h2&gt;
  
  
  The steps
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Sign up&lt;/li&gt;
&lt;li&gt;Create a project&lt;/li&gt;
&lt;li&gt;Create an API key&lt;/li&gt;
&lt;li&gt;Register a consumer and an endpoint&lt;/li&gt;
&lt;li&gt;Send&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Then check the delivery log and verify the signature where the webhook lands.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Sign up
&lt;/h2&gt;

&lt;p&gt;Go to &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt; and sign up with email, Google or GitHub. With email you get a sign-in link that's valid for 15 minutes. On first sign-in you create an organization (your company or team); plans, billing and members belong to the organization.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Project
&lt;/h2&gt;

&lt;p&gt;Create one project per product that sends webhooks. Each project has two environments:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Environment&lt;/th&gt;
&lt;th&gt;API key&lt;/th&gt;
&lt;th&gt;Messages&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Live&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sk_live_…&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Count toward your plan&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Test&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sk_test_…&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Not counted&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Start in the test environment, then switch to a live key when everything works.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. API key
&lt;/h2&gt;

&lt;p&gt;Create keys per environment under "API keys" in the dashboard. The key is shown once. Pick from five scopes:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Scope&lt;/th&gt;
&lt;th&gt;Allows&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;messages:send&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Sending messages&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;messages:retry&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Retrying deliveries&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;logs:read&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Reading delivery logs, consumers and endpoints&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;endpoints:write&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Creating, updating and deleting endpoints; rotating secrets&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;consumers:write&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Creating consumers&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The code in this post creates consumers and endpoints and reads logs, so give the key all five. In production, a server that only sends should get &lt;code&gt;messages:send&lt;/code&gt; alone. Keys can expire after 30 days, 90 days, a year, or never; organization owners and admins get an email 7 days before a key expires.&lt;/p&gt;

&lt;p&gt;Put the key in an environment variable. The SDK reads &lt;code&gt;WEBHOOK_ADMIN_API_KEY&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install webhookadmin
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;WEBHOOK_ADMIN_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sk_test_...
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  4-5. Consumer, endpoint, send
&lt;/h2&gt;

&lt;p&gt;A consumer is the customer who receives webhooks; &lt;code&gt;external_id&lt;/code&gt; is that customer's ID in your system. An endpoint is a URL where that consumer receives them. When you send, you pass the consumer's &lt;code&gt;external_id&lt;/code&gt;, an event type and a payload, and the message goes to every one of that consumer's endpoints subscribed to the event type.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;WebhookAdmin&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wha&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;WebhookAdmin&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// reads WEBHOOK_ADMIN_API_KEY (sk_test_…)&lt;/span&gt;

&lt;span class="c1"&gt;// Consumer: external_id is the customer's ID in your system&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;consumer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wha&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;consumers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;external_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'cus_1024'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'Example Inc.'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Endpoint: the secret is only returned here&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;endpoint&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wha&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;endpoints&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;consumer_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;consumer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'https://example.com/webhooks'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;event_types&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'invoice.paid'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;endpoint&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;secret&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// hand this whsec_… to the receiver&lt;/span&gt;

&lt;span class="c1"&gt;// Send: the same Idempotency-Key returns the same message for 24 hours&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wha&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;consumer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'cus_1024'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;event_type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'invoice.paid'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;invoice_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'inv_88'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;128000&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'inv_88-paid'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Check the delivery&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wha&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;deliveries&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;response_status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;response_head&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;About endpoints:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;URLs must be https on port 443 or 8443, in the test environment too. To receive on your own machine, put an ngrok or cloudflared tunnel in front of it (&lt;a href="https://webhookadmin.com/en/blog/test-webhooks-locally/" rel="noopener noreferrer"&gt;testing webhooks locally&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;IP-literal URLs, internal hostnames, and names that resolve to internal addresses are rejected with a 422.&lt;/li&gt;
&lt;li&gt;Omit &lt;code&gt;event_types&lt;/code&gt; to receive every event type.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;secret&lt;/code&gt; is only returned on creation. Later you can see it in the dashboard, or fetch it with developer access or above.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Sending returns &lt;code&gt;202 Accepted&lt;/code&gt; with &lt;code&gt;{ id, deliveries }&lt;/code&gt;, where &lt;code&gt;deliveries&lt;/code&gt; is the number of endpoints the message will go to. If no consumer has that &lt;code&gt;external_id&lt;/code&gt;, one is created on the spot (with no endpoints, so &lt;code&gt;deliveries&lt;/code&gt; is 0).&lt;/p&gt;

&lt;h2&gt;
  
  
  Why the Idempotency-Key
&lt;/h2&gt;

&lt;p&gt;Your own server can call the send API twice after a network error. Sends with the same &lt;code&gt;Idempotency-Key&lt;/code&gt; return the first message's &lt;code&gt;id&lt;/code&gt; for 24 hours instead of creating a second message. Build the key from something that happens once in your domain, like the invoice ID plus the event type. If you omit it, the SDK generates one and reuses it on its own retries.&lt;/p&gt;

&lt;h2&gt;
  
  
  Without the SDK
&lt;/h2&gt;

&lt;p&gt;The API is JSON over HTTP, so &lt;code&gt;fetch&lt;/code&gt; is enough:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'https://api.webhookadmin.com/v1/messages'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'POST'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`Bearer ${process.env.WEBHOOK_ADMIN_API_KEY}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s1"&gt;'Content-Type'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'application/json'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s1"&gt;'Idempotency-Key'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'inv_88-paid'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;consumer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'cus_1024'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;event_type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'invoice.paid'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;invoice_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'inv_88'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;128000&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// 202 { id: 'msg_…', deliveries: 1 }&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On top of this, the SDK waits for &lt;code&gt;retry-after&lt;/code&gt; and retries on 429, retries 5xx and network errors only for calls that are safe to repeat, adds an &lt;code&gt;Idempotency-Key&lt;/code&gt; automatically, and types responses and errors.&lt;/p&gt;

&lt;h2&gt;
  
  
  Check the delivery log
&lt;/h2&gt;

&lt;p&gt;Look under "Logs" in the dashboard, or call &lt;code&gt;GET /v1/messages/{id}&lt;/code&gt;. Each endpoint's attempts show the time, status code, first 1,024 bytes of the response body, duration and any error. If an attempt failed, read the response, fix the receiver, and replay the delivery (&lt;code&gt;POST /v1/deliveries/{id}/retry&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;To test an endpoint without triggering a real business event, send &lt;code&gt;webhook.test&lt;/code&gt; to just that endpoint with &lt;code&gt;POST /v1/endpoints/{id}/test&lt;/code&gt;. Test sends don't count toward usage.&lt;/p&gt;

&lt;h2&gt;
  
  
  Verify on the receiving side
&lt;/h2&gt;

&lt;p&gt;Every delivery carries a Standard Webhooks signature. The receiver verifies the raw body and headers with the &lt;code&gt;whsec_…&lt;/code&gt; from step 4:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;express&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'express'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'webhookadmin'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// whsec_…&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Verify against the raw body, before any JSON parsing&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/webhooks'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'application/json'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// { type, timestamp, data }&lt;/span&gt;
    &lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;listen&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;3000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Receivers don't need this SDK: the official Standard Webhooks libraries (Node, Python, Go, Ruby and others) verify the same signatures. The header and signature format is in &lt;a href="https://webhookadmin.com/en/docs/sdk/" rel="noopener noreferrer"&gt;signature verification&lt;/a&gt;. To drop duplicates, use the &lt;code&gt;webhook-id&lt;/code&gt; header; it stays the same across retries.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the Free plan covers
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Item&lt;/th&gt;
&lt;th&gt;Free plan&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Live messages&lt;/td&gt;
&lt;td&gt;50,000 a month (at the limit, new sends are refused until the 1st, UTC)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Projects&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Delivery log retention&lt;/td&gt;
&lt;td&gt;7 days&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API rate&lt;/td&gt;
&lt;td&gt;600 requests a minute&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Test messages, retries, test sends&lt;/td&gt;
&lt;td&gt;Not counted&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The customer portal and static source IPs start on Starter. All plan limits are on the &lt;a href="https://webhookadmin.com/en/#pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where to go next
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Step-by-step docs: &lt;a href="https://webhookadmin.com/en/docs/#signup" rel="noopener noreferrer"&gt;sign up&lt;/a&gt;, &lt;a href="https://webhookadmin.com/en/docs/#project" rel="noopener noreferrer"&gt;project&lt;/a&gt;, &lt;a href="https://webhookadmin.com/en/docs/#api-key" rel="noopener noreferrer"&gt;API key&lt;/a&gt;, &lt;a href="https://webhookadmin.com/en/docs/#consumer" rel="noopener noreferrer"&gt;consumer and endpoint&lt;/a&gt;, &lt;a href="https://webhookadmin.com/en/docs/#send" rel="noopener noreferrer"&gt;send&lt;/a&gt;, &lt;a href="https://webhookadmin.com/en/docs/#verify" rel="noopener noreferrer"&gt;verify&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Everything a sender needs: &lt;a href="https://webhookadmin.com/en/blog/how-to-send-webhooks/" rel="noopener noreferrer"&gt;how to send webhooks&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Why the signature looks the way it does: &lt;a href="https://webhookadmin.com/en/blog/standard-webhooks-explained/" rel="noopener noreferrer"&gt;Standard Webhooks explained&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All of this works on the free plan. Sign up at &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt; and send your first message with a test key.&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What does the Free plan include?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;50,000 live messages a month, one project, 7 days of delivery logs and 600 API requests a minute. Test-environment messages, retries and endpoint test sends don't count toward the monthly volume. The customer portal and static source IPs start on the Starter plan.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I send without the SDK?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes. The API is plain JSON over HTTP, so POST /v1/messages from fetch or curl works. The SDK adds retries on 429 and 5xx, automatic Idempotency-Keys and types.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do test-environment messages count toward my usage?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;No. Every project has a live and a test environment. Anything sent with an sk_test_ key is a test message and doesn't count toward your monthly limit or billing.&lt;/p&gt;




&lt;p&gt;Thanks for reading! If you try it, which step took longer than you expected? Let us know in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/send-first-webhook-node/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>node</category>
      <category>javascript</category>
      <category>webdev</category>
    </item>
    <item>
      <title>SSRF Protection for Webhook Senders: Check at Registration and at Send Time</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Tue, 10 Nov 2026 13:17:33 +0000</pubDate>
      <link>https://dev.to/shannonllc/ssrf-protection-for-webhook-senders-check-at-registration-and-at-send-time-1m53</link>
      <guid>https://dev.to/shannonllc/ssrf-protection-for-webhook-senders-check-at-registration-and-at-send-time-1m53</guid>
      <description>&lt;p&gt;Customers type in the URLs your webhooks go to, and sooner or later someone will try &lt;code&gt;http://169.254.169.254/&lt;/code&gt;. We cover checking URLs at registration and again at send time, and pinning the resolved IP, with Node.js code.&lt;/p&gt;

&lt;p&gt;Customers type in the URLs your webhooks go to. If you send to them without checks, someone can register &lt;code&gt;http://169.254.169.254/&lt;/code&gt; or the address of an internal admin panel, and your servers will make requests into your own network on their behalf. That's server-side request forgery (SSRF). The defense comes down to three rules: check the URL when it's registered and again right before each send, connect to the exact IP address you checked, and never follow redirects.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;Your webhook workers sit inside your network. Without checks, a customer-supplied URL can reach:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Cloud metadata services:&lt;/strong&gt; &lt;code&gt;169.254.169.254&lt;/code&gt; on AWS and Azure, &lt;code&gt;metadata.google.internal&lt;/code&gt; on GCP. These can hand out credentials.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Internal services:&lt;/strong&gt; anything in &lt;code&gt;10.0.0.0/8&lt;/code&gt; or &lt;code&gt;192.168.0.0/16&lt;/code&gt;, admin ports on &lt;code&gt;localhost&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your own APIs&lt;/strong&gt; that skip authentication for requests from inside the network.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you show response bodies in the customer's delivery log, the internal service's response can end up on the attacker's screen.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checks at registration
&lt;/h2&gt;

&lt;p&gt;When a customer adds an endpoint:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Parse it as a URL.&lt;/strong&gt; Use a standard parser and check the hostname it produces. The WHATWG URL parser normalizes &lt;code&gt;http://2130706433/&lt;/code&gt; and &lt;code&gt;http://0x7f.1/&lt;/code&gt; to &lt;code&gt;127.0.0.1&lt;/code&gt;, so checking the raw string misses them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Allow &lt;code&gt;https&lt;/code&gt; only.&lt;/strong&gt; Plain http lets anyone on the path read and modify payloads.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Restrict ports&lt;/strong&gt;, for example to 443 and 8443, so the URL can't target other services' ports.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reject credentials in the URL&lt;/strong&gt; (&lt;code&gt;https://user:pass@example.com/&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reject IP-literal hosts&lt;/strong&gt; such as &lt;code&gt;https://10.0.0.5/&lt;/code&gt; or &lt;code&gt;https://[::1]/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reject internal names:&lt;/strong&gt; &lt;code&gt;localhost&lt;/code&gt; and &lt;code&gt;*.localhost&lt;/code&gt;, &lt;code&gt;.local&lt;/code&gt;, &lt;code&gt;.internal&lt;/code&gt;, &lt;code&gt;.home.arpa&lt;/code&gt;, and single-label names. RFC 6761 says name resolution should always return a loopback address for localhost names (&lt;a href="https://www.rfc-editor.org/rfc/rfc6761" rel="noopener noreferrer"&gt;RFC 6761&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Resolve the name.&lt;/strong&gt; Look up both A and AAAA records; reject if any answer is internal, or if nothing resolves.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Failing at registration gives the customer an immediate, specific error. But step 7 only tells you about DNS at that moment.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checks at send time
&lt;/h2&gt;

&lt;p&gt;DNS rebinding defeats registration checks: the attacker registers their own domain, has it resolve to a public IP during registration, then switches it to &lt;code&gt;127.0.0.1&lt;/code&gt;. With a short TTL they can even return different answers to your check and to the connection that follows it.&lt;/p&gt;

&lt;p&gt;OWASP's SSRF cheat sheet says to resolve all IP addresses behind the domain (A and AAAA), apply the same checks to each, and disable redirect support in the HTTP client (&lt;a href="https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html" rel="noopener noreferrer"&gt;OWASP SSRF Prevention Cheat Sheet&lt;/a&gt;, checked on 2026-09-27). Before every send:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Resolve the name and check every returned IP. If any is internal, don't send.&lt;/li&gt;
&lt;li&gt;Connect to the IP you checked. Don't let the HTTP client resolve the name again.&lt;/li&gt;
&lt;li&gt;Use the original hostname for TLS SNI and certificate validation.&lt;/li&gt;
&lt;li&gt;Don't follow redirects; record a 3xx as a failure.&lt;/li&gt;
&lt;li&gt;Cap the time you wait and how much of the response you read.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Address ranges to block
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Range&lt;/th&gt;
&lt;th&gt;What it is&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;0.0.0.0/8&lt;/code&gt;, &lt;code&gt;127.0.0.0/8&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;"This host" and loopback&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;10.0.0.0/8&lt;/code&gt;, &lt;code&gt;172.16.0.0/12&lt;/code&gt;, &lt;code&gt;192.168.0.0/16&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Private networks (RFC 1918)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;100.64.0.0/10&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Carrier-grade NAT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;169.254.0.0/16&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Link-local, including cloud metadata&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;192.0.0.0/24&lt;/code&gt;, &lt;code&gt;192.0.2.0/24&lt;/code&gt;, &lt;code&gt;198.18.0.0/15&lt;/code&gt;, &lt;code&gt;198.51.100.0/24&lt;/code&gt;, &lt;code&gt;203.0.113.0/24&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Reserved, documentation and benchmarking&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;224.0.0.0/4&lt;/code&gt;, &lt;code&gt;240.0.0.0/4&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Multicast and reserved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;::1&lt;/code&gt;, &lt;code&gt;::&lt;/code&gt;, &lt;code&gt;fc00::/7&lt;/code&gt;, &lt;code&gt;fe80::/10&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;IPv6 loopback, unspecified, unique local, link-local&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;::ffff:0:0/96&lt;/code&gt;, &lt;code&gt;64:ff9b::/96&lt;/code&gt;, &lt;code&gt;2002::/16&lt;/code&gt;, &lt;code&gt;2001::/32&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;IPv6 forms that carry an IPv4 address (mapped, NAT64, 6to4, Teredo)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The last row is the one people miss. &lt;code&gt;::ffff:127.0.0.1&lt;/code&gt; is written as IPv6 but connects to IPv4 loopback.&lt;/p&gt;

&lt;h2&gt;
  
  
  A Node.js implementation
&lt;/h2&gt;

&lt;p&gt;Resolve, check, then pin the connection to the checked IP. Node's &lt;code&gt;net.BlockList&lt;/code&gt; evaluates IPv4-mapped IPv6 addresses (&lt;code&gt;::ffff:…&lt;/code&gt;) against its IPv4 rules. It also maps IPv4 addresses to that form when comparing them with IPv6 rules, so a broad IPv6 entry such as &lt;code&gt;::/8&lt;/code&gt; or &lt;code&gt;::ffff:0:0/96&lt;/code&gt; would block every IPv4 address - keep the IPv6 list specific.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;lookup&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'node:dns/promises'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'node:https'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;BlockList&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;LookupFunction&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'node:net'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;blocked&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BlockList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;net&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;bits&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'0.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'10.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'100.64.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'127.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'169.254.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'172.16.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'192.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'192.0.2.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'192.168.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'198.18.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;15&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'198.51.100.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'203.0.113.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'224.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'240.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;blocked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addSubnet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;net&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;bits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'ipv4'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;net&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;bits&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;128&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'::1'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;128&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'64:ff9b::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;96&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'2001::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'2002::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'fc00::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;7&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'fe80::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'ff00::'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;blocked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addSubnet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;net&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;bits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'ipv6'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// IPv4-mapped addresses such as ::ffff:127.0.0.1 are checked against the IPv4 rules above&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;safePost&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;rawUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Record&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;rawUrl&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// already passed the registration checks&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;addrs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;lookup&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hostname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;all&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// A and AAAA&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;addrs&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'no address'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;addrs&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;some&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;blocked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;check&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;address&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;family&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s1"&gt;'ipv6'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'ipv4'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'blocked address'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// don't tell the customer which internal IP it was&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;pinned&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;addrs&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="c1"&gt;// Never resolve again: connect to the address we just checked&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;pinnedLookup&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;LookupFunction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_host&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;opts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cb&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;opts&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;all&lt;/span&gt;&lt;span class="o"&gt;?:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;all&lt;/span&gt;
      &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cb&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;any&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;pinned&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;cb&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;pinned&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;address&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;pinned&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;family&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;reject&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;request&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'POST'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lookup&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;pinnedLookup&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;servername&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hostname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;15_000&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resume&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// no redirect following; a 3xx is returned as a failure&lt;/span&gt;
        &lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;statusCode&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;on&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'timeout'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;destroy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'timeout'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;on&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'error'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;reject&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;https.request&lt;/code&gt; still validates the certificate against the original hostname, so pinning the IP doesn't weaken TLS. The &lt;code&gt;timeout&lt;/code&gt; option is an idle timeout; add a separate timer if you need an overall deadline. &lt;code&gt;fetch&lt;/code&gt; doesn't make pinning easy, so use &lt;code&gt;https.request&lt;/code&gt; or an HTTP client that lets you choose the connect address.&lt;/p&gt;

&lt;h2&gt;
  
  
  Network-level defenses
&lt;/h2&gt;

&lt;p&gt;Application checks can have gaps. Network controls limit the damage when they do.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Send from an isolated egress.&lt;/strong&gt; Run webhook delivery somewhere that can't reach your internal network. The Standard Webhooks spec also recommends proxying webhook requests and isolating workers in private subnets (&lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks spec&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use an egress proxy.&lt;/strong&gt; Stripe's open-source &lt;a href="https://github.com/stripe/smokescreen" rel="noopener noreferrer"&gt;Smokescreen&lt;/a&gt; is an HTTP CONNECT proxy that resolves each requested hostname and checks that it's a publicly routable address before allowing the connection. Stripe uses it for outbound traffic such as webhooks.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Require tokens for instance metadata.&lt;/strong&gt; AWS IMDSv2 requires a session token that SSRF requests typically can't obtain; OWASP lists it as defense in depth.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For the rest of the sender and receiver security checks beyond SSRF, see the &lt;a href="https://webhookadmin.com/en/blog/webhook-security-checklist/" rel="noopener noreferrer"&gt;webhook security checklist&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to show customers when a check fails
&lt;/h2&gt;

&lt;p&gt;At registration, say why ("only https URLs are accepted", "internal hostnames can't be registered"). At send time, don't reveal which internal address the name resolved to, or you've built a network scanner. Log something like "destination address not allowed."&lt;/p&gt;

&lt;h2&gt;
  
  
  What Webhook Admin checks
&lt;/h2&gt;

&lt;p&gt;At registration, Webhook Admin enforces (as of 2026-09-27):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;https only, on port 443 or 8443&lt;/li&gt;
&lt;li&gt;No credentials in the URL&lt;/li&gt;
&lt;li&gt;No IP-literal hosts&lt;/li&gt;
&lt;li&gt;No &lt;code&gt;localhost&lt;/code&gt;, &lt;code&gt;.local&lt;/code&gt;, &lt;code&gt;.internal&lt;/code&gt;, &lt;code&gt;.localdomain&lt;/code&gt;, &lt;code&gt;.home.arpa&lt;/code&gt;, &lt;code&gt;.lan&lt;/code&gt; or &lt;code&gt;.intranet&lt;/code&gt; names, and no names without a dot&lt;/li&gt;
&lt;li&gt;A and AAAA lookups; names that resolve to internal addresses, or don't resolve, are rejected with a 422&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It checks name resolution again right before sending, never follows redirects, and times out after 15 seconds. See &lt;a href="https://webhookadmin.com/en/docs/api/#create-endpoint" rel="noopener noreferrer"&gt;create an endpoint&lt;/a&gt; for the API, and &lt;a href="https://webhookadmin.com/en/blog/how-to-send-webhooks/" rel="noopener noreferrer"&gt;how to send webhooks&lt;/a&gt; for the rest of what a sender needs.&lt;/p&gt;

&lt;p&gt;If you'd rather not build SSRF-safe delivery to customer URLs yourself, you can try Webhook Admin for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Isn't validating the URL at registration enough?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;No. A hostname that resolved to a public address when it was registered can be changed to resolve to 127.0.0.1 or 169.254.169.254 later. Resolve the name right before sending, check the result, and connect to that exact IP.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How do I test against localhost during development?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Put "allow private addresses" behind a setting that is off by default and only enabled in development, so it can never be on in production. To test with production-equivalent checks, give your local server a public https URL with an ngrok or cloudflared tunnel.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What about IPv6?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Resolve both A and AAAA records and check every answer. Besides ::1, fc00::/7 and fe80::/10, watch for IPv6 forms that embed an IPv4 address (IPv4-mapped, NAT64, 6to4, Teredo) - check the embedded IPv4 or block those ranges outright.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Do you check webhook URLs only at registration, or before every send? We'd love to hear in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/webhook-ssrf-protection/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>security</category>
      <category>node</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Shopify Webhooks: HMAC Verification, 5-Second Timeout, Retries</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Sat, 07 Nov 2026 13:17:32 +0000</pubDate>
      <link>https://dev.to/shannonllc/shopify-webhooks-hmac-verification-5-second-timeout-retries-jkj</link>
      <guid>https://dev.to/shannonllc/shopify-webhooks-hmac-verification-5-second-timeout-retries-jkj</guid>
      <description>&lt;p&gt;Shopify gives your endpoint 5 seconds to respond, retries 8 times over 4 hours, and can delete the subscription after that. We checked the docs and put the HMAC check, timeouts, retries and Node.js code in one place.&lt;/p&gt;

&lt;p&gt;Shopify gives your webhook endpoint 1 second to accept the connection and 5 seconds to respond. If it doesn't get a 200-series response in time, it retries 8 times over the next 4 hours, and after 8 consecutive failures it deletes the subscription if it was created through the Admin API. Every delivery is signed in &lt;code&gt;X-Shopify-Hmac-Sha256&lt;/code&gt; with a base64 HMAC-SHA256 of the raw body, keyed with your app's client secret. This post collects the behavior in one table, checked against Shopify's docs on 2026-09-27, then covers the common HMAC mistakes and how to structure a handler that fits in 5 seconds.&lt;/p&gt;

&lt;h2&gt;
  
  
  Shopify webhook behavior at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Topic&lt;/th&gt;
&lt;th&gt;Behavior&lt;/th&gt;
&lt;th&gt;Source&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Signature header&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-Shopify-Hmac-Sha256&lt;/code&gt; (HTTPS deliveries only)&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks/delivery-structure" rel="noopener noreferrer"&gt;Delivery structure&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Algorithm&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, base64&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks/subscribe/https" rel="noopener noreferrer"&gt;HTTPS delivery&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Key&lt;/td&gt;
&lt;td&gt;The app's client secret&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Signed content&lt;/td&gt;
&lt;td&gt;The raw request body, before any parsing&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Connection timeout&lt;/td&gt;
&lt;td&gt;1 second&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Total timeout&lt;/td&gt;
&lt;td&gt;5 seconds&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Success&lt;/td&gt;
&lt;td&gt;200-series&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks/troubleshoot" rel="noopener noreferrer"&gt;Troubleshooting&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retries&lt;/td&gt;
&lt;td&gt;8 times over the next 4 hours&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks/subscribe/https" rel="noopener noreferrer"&gt;HTTPS delivery&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Subscription removal&lt;/td&gt;
&lt;td&gt;After 8 consecutive failures, if created through the Admin API&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Warning emails&lt;/td&gt;
&lt;td&gt;Sent to the app's emergency developer email&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Duplicate key&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt; (unique per delivery)&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks/ignore-duplicates" rel="noopener noreferrer"&gt;Ignore duplicates&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ordering&lt;/td&gt;
&lt;td&gt;Not guaranteed within a topic or across topics for the same resource&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks" rel="noopener noreferrer"&gt;About webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Delivery guarantee&lt;/td&gt;
&lt;td&gt;Not always guaranteed; Shopify recommends reconciliation jobs&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Headers on every delivery
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Header&lt;/th&gt;
&lt;th&gt;Contents&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Topic&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Topic name, for example &lt;code&gt;products/update&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Hmac-Sha256&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Base64 HMAC signature&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Shop-Domain&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The store's &lt;code&gt;myshopify.com&lt;/code&gt; domain&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-API-Version&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;API version used to serialize the payload&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Unique per delivery; use it to deduplicate&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Triggered-At&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;When Shopify triggered the delivery&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Event-Id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shared by all deliveries from the same merchant action&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;X-Shopify-Name&lt;/code&gt; (optional)&lt;/td&gt;
&lt;td&gt;The name you gave the subscription&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Shopify notes that HTTP/2 often lowercases header names, so treat them case-insensitively.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three reasons the HMAC doesn't match
&lt;/h2&gt;

&lt;p&gt;HMAC failures come up again and again on Shopify's developer forum (&lt;a href="https://community.shopify.dev/t/fail-to-verify-hmac-x-shopify-hmac-sha256-header-in-nestjs/5092" rel="noopener noreferrer"&gt;NestJS&lt;/a&gt;, &lt;a href="https://community.shopify.dev/t/hmac-webhook-verification-failing-need-technical-assistance/18871" rel="noopener noreferrer"&gt;another thread&lt;/a&gt;). Almost always it's one of these:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The body was parsed first.&lt;/strong&gt; Shopify's docs warn that middleware like &lt;code&gt;express.json()&lt;/code&gt; parses the body before your verification code runs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Comparing hex.&lt;/strong&gt; The header is base64. A &lt;code&gt;digest('hex')&lt;/code&gt; string won't match it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Wrong secret.&lt;/strong&gt; The key is the app's client secret, not a per-webhook value. Development and production apps have different client secrets.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Verifying in Node.js
&lt;/h2&gt;

&lt;p&gt;Following Shopify's own example: compute a base64 HMAC over the raw body and compare in constant time.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nx"&gt;crypto&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:crypto&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;express&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;CLIENT_SECRET&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;SHOPIFY_CLIENT_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Raw body for this route only; register before express.json()&lt;/span&gt;
&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/webhooks/shopify&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}),&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;received&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;x-shopify-hmac-sha256&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;''&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;digest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;crypto&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;CLIENT_SECRET&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;digest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;digest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;received&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;crypto&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;timingSafeEqual&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;401&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="c1"&gt;// Deduplicate on X-Shopify-Webhook-Id with a unique constraint&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;webhookId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;x-shopify-webhook-id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;INSERT INTO shopify_deliveries (id) VALUES ($1) ON CONFLICT DO NOTHING&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;webhookId&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;rowCount&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;shopify&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;x-shopify-topic&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="na"&gt;shop&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;x-shopify-shop-domain&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="na"&gt;triggeredAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;x-shopify-triggered-at&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;utf8&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// well inside 5 seconds&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;use&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In NestJS, start the app with &lt;code&gt;NestFactory.create(AppModule, { rawBody: true })&lt;/code&gt; and read the unparsed Buffer from &lt;code&gt;req.rawBody&lt;/code&gt; via &lt;code&gt;RawBodyRequest&lt;/code&gt; (&lt;a href="https://docs.nestjs.com/faq/raw-body" rel="noopener noreferrer"&gt;NestJS docs&lt;/a&gt;). Other frameworks are covered in &lt;a href="https://webhookadmin.com/en/blog/webhook-raw-body-by-framework/" rel="noopener noreferrer"&gt;getting the raw request body&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fitting in 5 seconds
&lt;/h2&gt;

&lt;p&gt;Five seconds is short compared with most providers; &lt;a href="https://webhookadmin.com/en/blog/webhook-timeouts/" rel="noopener noreferrer"&gt;webhook timeouts&lt;/a&gt; compares them. Shopify's troubleshooting guide says to resolve timeouts by delaying processing until after you've sent the response. The handler should do four things only:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Verify the HMAC.&lt;/li&gt;
&lt;li&gt;Drop duplicates by &lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Enqueue.&lt;/li&gt;
&lt;li&gt;Return 200.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Product syncs and external API calls belong in a worker. Shopify also recommends enabling Keep-Alive so connections are reused.&lt;/p&gt;

&lt;h2&gt;
  
  
  Planning for retries and subscription removal
&lt;/h2&gt;

&lt;p&gt;Retries end 4 hours after the failure, and a subscription that fails 8 times in a row is gone. If your endpoint is down for more than about 4 hours, you lose those events and have to recreate the subscription.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;If a subscription was removed:&lt;/strong&gt; fix the cause, recreate the subscription, and fetch current data through the Admin API to cover the gap. The missed events won't be resent.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reconcile regularly:&lt;/strong&gt; Shopify says webhook delivery isn't always guaranteed and recommends reconciliation jobs that periodically fetch data from Shopify. A daily job catches gaps even when nothing looked wrong.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Route the warning emails somewhere people read:&lt;/strong&gt; failure warnings go to the app's emergency developer email. Use a team address.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check delivery status&lt;/strong&gt; under your app's Overview and Logs in the Dev Dashboard.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Ordering
&lt;/h2&gt;

&lt;p&gt;Shopify doesn't guarantee order and recommends sorting by the &lt;code&gt;X-Shopify-Triggered-At&lt;/code&gt; header or the payload's &lt;code&gt;updated_at&lt;/code&gt;. When updates for the same resource arrive out of order, ignore any update older than what you've stored:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;title&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;title&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;updated_at&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;updated_at&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;updated_at&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;OR&lt;/span&gt; &lt;span class="n"&gt;updated_at&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;updated_at&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For more on deduplication see &lt;a href="https://webhookadmin.com/en/blog/webhook-idempotency-duplicates/" rel="noopener noreferrer"&gt;handling duplicate webhooks&lt;/a&gt;, and for debugging signatures see &lt;a href="https://webhookadmin.com/en/blog/webhook-signature-verification-failed/" rel="noopener noreferrer"&gt;why webhook signature verification fails&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  When you're the one sending
&lt;/h2&gt;

&lt;p&gt;If your own product sends webhooks to customers or apps the way Shopify does, you need retries, signatures, delivery logs and failure alerts. Choosing a retry window is covered in &lt;a href="https://webhookadmin.com/en/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;designing webhook retries&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Webhook Admin provides these through an API: Standard Webhooks signatures, 8 attempts over about 28 hours by default (you can choose the number of retries and the interval per endpoint) with a 15-second timeout per attempt, and a log of every attempt with the status code and the first 1,024 bytes of the response. It alerts you (Slack, Teams, email or a webhook) when deliveries keep failing, and disables an endpoint after five days of failures until you set it back to active. The free plan includes 50,000 messages a month: &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Why does my Shopify HMAC check fail when I compare hex strings?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Shopify sends the HMAC-SHA256 base64-encoded. digest('hex') gives the same bytes written differently, so the strings never match. Compute with digest('base64'), or compare the raw bytes after base64-decoding the header.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;My webhook subscription disappeared. How do I get it back?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Fix whatever was failing, then recreate the subscription, as Shopify's troubleshooting guide says. Events from while it was gone won't be redelivered, so fetch current data through the Admin API to catch up.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How do I detect duplicate Shopify webhooks?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Use X-Shopify-Webhook-Id. Shopify's guide says to look it up in persistent storage, skip processing and return success if it's there, and otherwise process the delivery and save the ID. X-Shopify-Event-Id is shared by every delivery from the same merchant action, so it isn't a duplicate key.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Has Shopify ever removed one of your webhook subscriptions, and how did you notice? Tell us in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/shopify-webhooks-hmac-retries/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>webdev</category>
      <category>node</category>
      <category>security</category>
    </item>
    <item>
      <title>Handling Duplicate Webhooks: Idempotency with Event IDs</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Thu, 05 Nov 2026 13:17:33 +0000</pubDate>
      <link>https://dev.to/shannonllc/handling-duplicate-webhooks-idempotency-with-event-ids-5h4j</link>
      <guid>https://dev.to/shannonllc/handling-duplicate-webhooks-idempotency-with-event-ids-5h4j</guid>
      <description>&lt;p&gt;Your handler finishes, the response gets lost, and the sender delivers the same event again. We cover three ways to make receivers idempotent, how to handle duplicates that arrive at the same time, and where Stripe, GitHub, Shopify and others put the event ID.&lt;/p&gt;

&lt;p&gt;Webhook senders retry anything they couldn't confirm was delivered. If your handler finished its work but the response never made it back, the sender sees a failure and sends the event again. So the same event will sometimes arrive twice or more, and deduplication is the receiver's job: record each event's ID under a unique constraint, and when you see an ID again, skip the work and return 2xx. This post covers why duplicates happen, three ways to guard against them, what to do when two copies arrive at once, and where each provider puts its event ID.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why duplicates happen
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;You received it, but your 2xx didn't reach the sender.&lt;/strong&gt; The connection dropped after you'd done the work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your work finished after the sender's timeout.&lt;/strong&gt; The sender gave up and recorded a failure; your handler kept going and completed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sender-side replays.&lt;/strong&gt; A queue ran the same job twice, or someone replayed a delivery from the sender's log.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Shopify's docs say it plainly: your app might receive the same webhook more than once, for example after a network timeout or a retry (&lt;a href="https://shopify.dev/docs/apps/build/webhooks/ignore-duplicates" rel="noopener noreferrer"&gt;Shopify&lt;/a&gt;, checked on 2026-09-27). Senders promise at-least-once delivery; exactly-once processing is up to you.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where each provider puts the event ID
&lt;/h2&gt;

&lt;p&gt;Checked against official documentation on 2026-09-27.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Sender&lt;/th&gt;
&lt;th&gt;ID location&lt;/th&gt;
&lt;th&gt;Same on retry?&lt;/th&gt;
&lt;th&gt;Notes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Standard Webhooks&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;webhook-id&lt;/code&gt; header&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;The spec recommends using it as the idempotency key&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Stripe&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;id&lt;/code&gt; in the body (&lt;code&gt;evt_…&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Two separately generated Event objects can describe one change; identify those by &lt;code&gt;data.object&lt;/code&gt; ID plus &lt;code&gt;type&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-GitHub-Delivery&lt;/code&gt; header&lt;/td&gt;
&lt;td&gt;Yes, also on redelivery&lt;/td&gt;
&lt;td&gt;A GUID per delivery&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shopify&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt; header&lt;/td&gt;
&lt;td&gt;-&lt;/td&gt;
&lt;td&gt;Unique per delivery; use it to deduplicate. &lt;code&gt;X-Shopify-Event-Id&lt;/code&gt; is shared by all deliveries from one merchant action&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Slack&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;event_id&lt;/code&gt; in the body&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;td&gt;Unique across all workspaces; retries carry &lt;code&gt;x-slack-retry-num&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LINE&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;webhookEventId&lt;/code&gt; in the body&lt;/td&gt;
&lt;td&gt;-&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;deliveryContext.isRedelivery&lt;/code&gt; is true on redeliveries&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Sources: &lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks spec&lt;/a&gt;, &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;, &lt;a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads" rel="noopener noreferrer"&gt;GitHub headers&lt;/a&gt;, &lt;a href="https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks" rel="noopener noreferrer"&gt;GitHub best practices&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/ignore-duplicates" rel="noopener noreferrer"&gt;Shopify duplicates&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/delivery-structure" rel="noopener noreferrer"&gt;Shopify headers&lt;/a&gt;, &lt;a href="https://docs.slack.dev/apis/events-api/" rel="noopener noreferrer"&gt;Slack&lt;/a&gt;, &lt;a href="https://developers.line.biz/en/reference/messaging-api/" rel="noopener noreferrer"&gt;LINE&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Shopify's two IDs do different jobs: &lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt; to drop duplicate deliveries, &lt;code&gt;X-Shopify-Event-Id&lt;/code&gt; to correlate deliveries across topics that came from the same merchant action.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three ways to guard against duplicates
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. A unique constraint
&lt;/h3&gt;

&lt;p&gt;The simplest version. After verifying the signature, insert the ID into a table with a unique constraint. If nothing was inserted, it's a duplicate: return 2xx.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/webhooks&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}),&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;verifyOr400&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// sends 400 and returns undefined on a bad signature&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;INSERT INTO processed_webhooks (id, received_at) VALUES ($1, now()) ON CONFLICT (id) DO NOTHING&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;rowCount&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// seen before: acknowledge, don't process&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The weakness: if the process dies after the insert but before the job is enqueued, the event is marked as seen and never processed. If enqueueing isn't reliable, use the next approach.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Record the ID and apply the change in one transaction
&lt;/h3&gt;

&lt;p&gt;Put the ID insert and the business update in the same transaction. Then "recorded but not processed" and "processed but not recorded" can't happen.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;transaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;INSERT INTO processed_webhooks (id, received_at) VALUES ($1, now()) ON CONFLICT (id) DO NOTHING&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;rowCount&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// duplicate&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;UPDATE invoices SET status = $1, paid_at = $2 WHERE id = $3&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;paid&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;paid_at&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;invoice_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt; &lt;span class="c1"&gt;// any failure rolls back both, and the next retry starts clean&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the handler calls an external API, pass an idempotency key derived from the event ID so a retried handler doesn't repeat that call.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Make the write itself idempotent
&lt;/h3&gt;

&lt;p&gt;Some operations produce the same result no matter how often they run: "mark the invoice paid," "overwrite the user's plan with this value." For those, an upsert (&lt;code&gt;INSERT … ON CONFLICT DO UPDATE&lt;/code&gt;) makes duplicates harmless without any tracking.&lt;/p&gt;

&lt;p&gt;Operations that accumulate - "add 100 points," "send an email" - are not like that, and need approach 1 or 2.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two copies at the same moment
&lt;/h2&gt;

&lt;p&gt;With short retry intervals, the second copy can arrive while the first is still being handled. If your code does "check whether the ID exists, then process and insert," both requests see "not yet" and both get processed.&lt;/p&gt;

&lt;p&gt;Insert first, under the unique constraint, and only continue when the insert succeeds. The database lets exactly one request through. Both code samples above work this way. For long-running work, keep a &lt;code&gt;status&lt;/code&gt; (processing / done) and a &lt;code&gt;started_at&lt;/code&gt;, and treat rows stuck in "processing" past a deadline as failed so they can be retried. Stripe's guide to processing undelivered events uses the same processing / processed split (&lt;a href="https://docs.stripe.com/webhooks/process-undelivered-events" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  How long to keep IDs
&lt;/h2&gt;

&lt;p&gt;Longer than the sender could plausibly send the same event again:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Automatic retry windows (Stripe: up to 3 days in live mode; Shopify: 4 hours)&lt;/li&gt;
&lt;li&gt;Manual replays (Stripe: 15 days from the Dashboard, 30 days from the CLI; GitHub: deliveries from the past 3 days can be redelivered)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keeping IDs for 30 to 90 days covers most cases. Delete older rows on a schedule.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why not hash the payload
&lt;/h2&gt;

&lt;p&gt;Distinct events can have identical bodies - two identical payments in the same second, for instance. And some senders change parts of the body, such as a timestamp, between attempts. Use the ID the sender assigns to each event.&lt;/p&gt;

&lt;p&gt;Handling events that arrive out of order (discarding stale updates by timestamp or version) is covered in &lt;a href="https://webhookadmin.com/en/blog/webhook-out-of-order-events/" rel="noopener noreferrer"&gt;out-of-order webhooks&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What senders have to get right
&lt;/h2&gt;

&lt;p&gt;Receivers can only deduplicate if the sender does two things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Give every event a unique ID and &lt;strong&gt;send the same ID on every retry&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Include the ID in the signed content so it can't be altered in transit.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Standard Webhooks signs &lt;code&gt;id.timestamp.body&lt;/code&gt;, which covers both. The sender-side equivalent - avoiding double sends when you call a delivery API - is covered in &lt;a href="https://webhookadmin.com/en/blog/idempotency-key-api/" rel="noopener noreferrer"&gt;idempotency keys for event APIs&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Webhooks from Webhook Admin
&lt;/h2&gt;

&lt;p&gt;Webhook Admin gives each message a &lt;code&gt;msg_…&lt;/code&gt; ID and sends it in the &lt;code&gt;webhook-id&lt;/code&gt; header. Retries and manual replays from the dashboard carry the same &lt;code&gt;webhook-id&lt;/code&gt;; only &lt;code&gt;webhook-timestamp&lt;/code&gt; and the signature are regenerated. After verifying the signature as described in &lt;a href="https://webhookadmin.com/en/docs/sdk/#request" rel="noopener noreferrer"&gt;the request format&lt;/a&gt;, store &lt;code&gt;webhook-id&lt;/code&gt; under a unique constraint and duplicates are handled. Automatic retries end after about 28 hours by default (up to 3 days with a per-endpoint setting), but deliveries can be replayed by hand from the log, so keep IDs for longer than your plan's log retention (7 days on Free, 30 on Starter, 90 on Pro and Business).&lt;/p&gt;

&lt;p&gt;If you'd rather not build stable IDs, retries and signing on the sending side, you can try Webhook Admin for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;How long should I keep processed event IDs?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Longer than the sender might send the same event again, including manual resends, not just automatic retries. Stripe, for example, retries automatically for up to 3 days but allows CLI resends up to 30 days after an event is created.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I deduplicate on a hash of the payload?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Not reliably. Two distinct events can have identical bodies (two identical payments in the same second), and some senders change parts of the body between attempts. Use the ID the sender assigns to each event.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What if two copies of the same event arrive at the same time?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If your code checks for the ID and then inserts it, both requests can see "not there yet" and both get processed. Insert first under a unique constraint and only process when the insert succeeds; the database then lets exactly one through.&lt;/p&gt;




&lt;p&gt;Thanks for reading! How do you deduplicate webhooks: a unique constraint, a cache, or something else? We'd love to hear in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/webhook-idempotency-duplicates/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>api</category>
      <category>database</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Monitoring Outgoing Webhooks: Failure Rates, Backlogs, and Alerts</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Tue, 03 Nov 2026 13:17:33 +0000</pubDate>
      <link>https://dev.to/shannonllc/monitoring-outgoing-webhooks-failure-rates-backlogs-and-alerts-3bbh</link>
      <guid>https://dev.to/shannonllc/monitoring-outgoing-webhooks-failure-rates-backlogs-and-alerts-3bbh</guid>
      <description>&lt;p&gt;When you send webhooks, two numbers tell you most of what you need: how long each endpoint has been failing, and how many deliveries are waiting to be retried. We cover what to measure, when to alert and whom, and how to warn people before disabling an endpoint.&lt;/p&gt;

&lt;p&gt;When you send webhooks, two numbers tell you most of what you need: how long each endpoint has been failing, and how many deliveries are waiting to be retried. The first tells you a particular customer's receiver is broken. The second tells you your own sending pipeline is backing up. This post covers what to measure, when to alert and whom, and the order in which to warn people before you disable an endpoint.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to measure
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;Scope&lt;/th&gt;
&lt;th&gt;What it tells you&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Time failing&lt;/td&gt;
&lt;td&gt;Per endpoint&lt;/td&gt;
&lt;td&gt;Whether the receiver is broken; counted from the first failure&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retry backlog&lt;/td&gt;
&lt;td&gt;Whole environment&lt;/td&gt;
&lt;td&gt;Whether your pipeline is stuck or many endpoints are failing at once&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Failure rate&lt;/td&gt;
&lt;td&gt;Per endpoint and overall&lt;/td&gt;
&lt;td&gt;Trends; the overall number is for day-over-day comparison&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Latency distribution&lt;/td&gt;
&lt;td&gt;Per endpoint&lt;/td&gt;
&lt;td&gt;Slow endpoints tying up workers; endpoints near the timeout fail next&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Disabled endpoints&lt;/td&gt;
&lt;td&gt;Whole environment&lt;/td&gt;
&lt;td&gt;Whether auto-disabling is increasing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Deliveries sent&lt;/td&gt;
&lt;td&gt;Whole environment&lt;/td&gt;
&lt;td&gt;Whether events stopped flowing (a sudden drop to zero is an incident too)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Why not the average failure rate
&lt;/h3&gt;

&lt;p&gt;Say you send 100,000 messages a day to 500 endpoints. One endpoint can be down all day, and if it receives 0.2% of the traffic, your overall failure rate moves by 0.2%. Meanwhile an endpoint that receives one message a day shows a 100% failure rate after a single blip. The overall rate is useful for trends; to spot a broken receiver, track how long each endpoint has been failing.&lt;/p&gt;

&lt;h3&gt;
  
  
  Tracking how long an endpoint has been failing
&lt;/h3&gt;

&lt;p&gt;Add one column to your endpoints table: when the current run of failures started. Clear it on success, set it on failure if it's empty.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- update after every delivery attempt&lt;/span&gt;
&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;endpoints&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;failing_since&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;CASE&lt;/span&gt;
  &lt;span class="k"&gt;WHEN&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;success&lt;/span&gt; &lt;span class="k"&gt;THEN&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;
  &lt;span class="k"&gt;ELSE&lt;/span&gt; &lt;span class="n"&gt;COALESCE&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;failing_since&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;END&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;endpoint_id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;-- endpoints failing for over an hour&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;failing_since&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;endpoints&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;failing_since&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;
  &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;failing_since&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;now&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;INTERVAL&lt;/span&gt; &lt;span class="s1"&gt;'1 hour'&lt;/span&gt;
  &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'active'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The same column drives both "alert after an hour" and "disable after five days."&lt;/p&gt;

&lt;h3&gt;
  
  
  Retry backlog
&lt;/h3&gt;

&lt;p&gt;The backlog is the number of deliveries that failed and are waiting for their next attempt. It jumps when many endpoints fail together, and also when your own sending breaks (DNS, egress network), so put a threshold on the environment-wide number separately from per-endpoint alerts.&lt;/p&gt;

&lt;h2&gt;
  
  
  When to alert
&lt;/h2&gt;

&lt;p&gt;Alert on stages, not attempts. Alerting on every failed attempt buries the alerts that matter.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Failing for a sustained period&lt;/strong&gt; (say, one hour). Filters out blips; what's left needs fixing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Retries exhausted.&lt;/strong&gt; That event won't arrive on its own anymore; someone has to decide whether to replay it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Endpoint disabled.&lt;/strong&gt; New events stop or are held; someone has to re-enable it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backlog over a threshold&lt;/strong&gt; (say, 1,000). A candidate for an incident in your own pipeline.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Group alerts per endpoint, for example at most one an hour, so a long outage doesn't produce an alert per retry.&lt;/p&gt;

&lt;h2&gt;
  
  
  Whom to alert
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Recipient&lt;/th&gt;
&lt;th&gt;What&lt;/th&gt;
&lt;th&gt;Channel&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Your operations team&lt;/td&gt;
&lt;td&gt;Every stage, backlog growth&lt;/td&gt;
&lt;td&gt;Slack, Teams, email, your monitoring system&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The endpoint's owner (your customer)&lt;/td&gt;
&lt;td&gt;Failures and disabling of their own endpoints&lt;/td&gt;
&lt;td&gt;Email, the customer portal&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Most failing endpoints are broken on the receiving side: an outage, an expired certificate, a URL that changed. The customer is the one who can fix it. If only your team hears about it, someone on your team has to contact the customer every time.&lt;/p&gt;

&lt;h2&gt;
  
  
  How other providers do it
&lt;/h2&gt;

&lt;p&gt;Checked against official documentation on 2026-09-27:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Provider&lt;/th&gt;
&lt;th&gt;Notification&lt;/th&gt;
&lt;th&gt;Stopping&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stripe&lt;/td&gt;
&lt;td&gt;Emails you when webhooks are failing (live mode)&lt;/td&gt;
&lt;td&gt;Retries each event for up to 3 days&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shopify&lt;/td&gt;
&lt;td&gt;Sends warning emails to the app's emergency developer email&lt;/td&gt;
&lt;td&gt;Deletes Admin API subscriptions after 8 consecutive failures&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Slack&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;td&gt;Disables event subscriptions when over 95% of attempts in 60 minutes fail&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Contentstack&lt;/td&gt;
&lt;td&gt;One email to the owner, not one per failure&lt;/td&gt;
&lt;td&gt;Disables the webhook after 10 consecutive failures with no success in between&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Sources: &lt;a href="https://docs.stripe.com/billing/subscriptions/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/subscribe/https" rel="noopener noreferrer"&gt;Shopify&lt;/a&gt;, &lt;a href="https://docs.slack.dev/apis/events-api/" rel="noopener noreferrer"&gt;Slack&lt;/a&gt;, &lt;a href="https://www.contentstack.com/docs/developers/set-up-webhooks/webhook-circuit-breaker" rel="noopener noreferrer"&gt;Contentstack&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Contentstack's single email on disable is one answer to alert noise. The trade-off is that without an earlier warning, the customer first hears about it after deliveries have already stopped.&lt;/p&gt;

&lt;h2&gt;
  
  
  Warn before you disable
&lt;/h2&gt;

&lt;p&gt;Auto-disabling protects your workers from endpoints that will never answer, but from that moment the customer receives nothing. Give them a chance to fix it first:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;After an hour of failures, notify your team and the customer.&lt;/li&gt;
&lt;li&gt;When an event exhausts its retries, notify again and mention that it can be replayed.&lt;/li&gt;
&lt;li&gt;When you disable the endpoint, notify and explain how to re-enable it (dashboard or API).&lt;/li&gt;
&lt;li&gt;Decide in advance what happens to events from the disabled period: send them on re-enable, or replay by hand.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Make the time to disable longer than your retry window. Disabling mid-window throws away events that could still have been delivered.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to put in the alert
&lt;/h2&gt;

&lt;p&gt;Enough for someone to decide without opening a dashboard:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The environment or project and the endpoint URL&lt;/li&gt;
&lt;li&gt;When the failures started&lt;/li&gt;
&lt;li&gt;The latest status code and the start of the response (for example &lt;code&gt;503 Service Unavailable&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;A link to the delivery log&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Response bodies can contain the receiver's error messages; &lt;a href="https://webhookadmin.com/en/blog/webhook-delivery-logs/" rel="noopener noreferrer"&gt;what to log for outgoing webhooks&lt;/a&gt; covers what to keep.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Webhook Admin shows and sends
&lt;/h2&gt;

&lt;p&gt;The project overview in Webhook Admin shows deliveries, success rate, failures and average duration over the last 24 hours, the retry backlog, the number of disabled endpoints, and daily successes and failures for the past 7 days. Alerts follow the stages above: an endpoint failing for an hour or a message out of retries (at most once an hour per endpoint), an endpoint auto-disabled after five days, more than 1,000 retries waiting in an environment, and usage thresholds. They go to Slack, Microsoft Teams, email, a signed webhook or Chatwork, with the endpoint URL and a dashboard link.&lt;/p&gt;

&lt;p&gt;Channel setup, defaults and test alerts are in &lt;a href="https://webhookadmin.com/en/blog/webhook-failure-alerts-setup/" rel="noopener noreferrer"&gt;the alerts setup guide&lt;/a&gt;, and the retry schedule in &lt;a href="https://webhookadmin.com/en/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;designing webhook retries&lt;/a&gt;. Log retention by plan is on the &lt;a href="https://webhookadmin.com/en/#pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you'd like delivery monitoring and alerts without building them, you can try Webhook Admin for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;At what failure rate should I alert?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Rather than a threshold on the overall failure rate, alert per endpoint on duration, for example when an endpoint has been failing for an hour. One dead endpoint barely moves the global rate, while a single failure on a low-volume endpoint looks like 100%.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Should I notify my customers too?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes. Most failing endpoints are broken on the receiver's side - an outage, an expired certificate, a changed URL - and only the customer can fix them. Stripe and Shopify both email the receiving developer when deliveries keep failing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;We get too many alerts. What should we change?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Group alerts for the same endpoint (at most one an hour, say) and alert on stages - failing for a while, retries exhausted, endpoint disabled - instead of on every failed attempt. Transient failures then stop drowning out real ones.&lt;/p&gt;




&lt;p&gt;Thanks for reading! What do you alert on for outgoing webhooks today? Let us know in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/webhook-monitoring-alerts/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>monitoring</category>
      <category>devops</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Webhook Response Status Codes: What to Return and What Senders Do</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Sat, 31 Oct 2026 13:17:35 +0000</pubDate>
      <link>https://dev.to/shannonllc/webhook-response-status-codes-what-to-return-and-what-senders-do-501l</link>
      <guid>https://dev.to/shannonllc/webhook-response-status-codes-what-to-return-and-what-senders-do-501l</guid>
      <description>&lt;p&gt;Should your webhook handler return 200, 202, 400 or 500? We cover what to return in each situation and how Stripe, Shopify, GitHub, Slack, LINE and Standard Webhooks treat non-2xx responses, redirects, 410 and 429.&lt;/p&gt;

&lt;p&gt;A webhook receiver really only needs three answers. Return 2xx when you've received the event. Return 400 or 401 when the request itself is invalid, such as a signature that doesn't match. Return 5xx when something on your side failed temporarily and you want the sender to try again. Most senders count only 2xx as delivered and retry everything else. This post covers what to return in each situation and how the major providers handle each class of response.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the receiver should return
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Situation&lt;/th&gt;
&lt;th&gt;Return&lt;/th&gt;
&lt;th&gt;Typical sender behavior&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Received and recorded (work still pending)&lt;/td&gt;
&lt;td&gt;200 or 204&lt;/td&gt;
&lt;td&gt;Success, no retry&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The same event again (duplicate)&lt;/td&gt;
&lt;td&gt;200 or 204&lt;/td&gt;
&lt;td&gt;Success, no retry&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Bad signature or missing headers&lt;/td&gt;
&lt;td&gt;400 or 401&lt;/td&gt;
&lt;td&gt;Failure; most senders retry&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Unknown event type&lt;/td&gt;
&lt;td&gt;200 or 204&lt;/td&gt;
&lt;td&gt;Success; accept and ignore&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Temporary failure (database down)&lt;/td&gt;
&lt;td&gt;500 or 503&lt;/td&gt;
&lt;td&gt;Failure; retried&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Processing took longer than the timeout&lt;/td&gt;
&lt;td&gt;(no response)&lt;/td&gt;
&lt;td&gt;Failure; retried&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;This URL should no longer receive events&lt;/td&gt;
&lt;td&gt;410&lt;/td&gt;
&lt;td&gt;Depends on the sender&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Three rows people get wrong:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Return 2xx for duplicates.&lt;/strong&gt; A 4xx tells the sender the delivery failed, and it will keep retrying.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Return 2xx for event types you don't handle.&lt;/strong&gt; Otherwise every new event type the sender adds becomes a stream of failures on your side.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Most senders retry 4xx too.&lt;/strong&gt; That's fine: once you fix a wrong secret, the next retry verifies.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  200 vs 204
&lt;/h2&gt;

&lt;p&gt;No difference. Stripe's docs describe a &lt;code&gt;200&lt;/code&gt; as a successful delivery and talk about success as &lt;code&gt;2xx&lt;/code&gt;; Shopify treats any 200-series response as successful; GitHub asks for a 2XX within 10 seconds (all checked on 2026-09-27). An empty 204 and a 200 with a short body are equivalent.&lt;/p&gt;

&lt;p&gt;Senders often store the response body in their delivery log, so a short reason on errors helps whoever reads that log. Don't return personal data or stack traces.&lt;/p&gt;

&lt;h2&gt;
  
  
  How the major senders handle responses
&lt;/h2&gt;

&lt;p&gt;Checked against each provider's official documentation on 2026-09-27.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Sender&lt;/th&gt;
&lt;th&gt;Success&lt;/th&gt;
&lt;th&gt;3xx&lt;/th&gt;
&lt;th&gt;Non-2xx&lt;/th&gt;
&lt;th&gt;Timeout&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stripe&lt;/td&gt;
&lt;td&gt;2xx&lt;/td&gt;
&lt;td&gt;Failure&lt;/td&gt;
&lt;td&gt;Retries with exponential backoff for up to 3 days (live)&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shopify&lt;/td&gt;
&lt;td&gt;200-series&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;td&gt;Up to 8 retries over 4 hours, then the subscription is removed&lt;/td&gt;
&lt;td&gt;5 s (1 s to connect)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub&lt;/td&gt;
&lt;td&gt;2XX&lt;/td&gt;
&lt;td&gt;Failure (anything other than 2XX)&lt;/td&gt;
&lt;td&gt;No automatic retries; redeliver manually or via API&lt;/td&gt;
&lt;td&gt;10 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Slack (Events API)&lt;/td&gt;
&lt;td&gt;2xx&lt;/td&gt;
&lt;td&gt;More than 2 redirects is a failure&lt;/td&gt;
&lt;td&gt;Retries immediately, after 1 min and after 5 min; &lt;code&gt;x-slack-no-retry: 1&lt;/code&gt; opts out&lt;/td&gt;
&lt;td&gt;3 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LINE&lt;/td&gt;
&lt;td&gt;200-series&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;td&gt;Redelivery only if you enable it (attempt count not disclosed)&lt;/td&gt;
&lt;td&gt;2 s (&lt;code&gt;request_timeout&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Standard Webhooks (spec)&lt;/td&gt;
&lt;td&gt;2xx&lt;/td&gt;
&lt;td&gt;Failure; update the URL instead&lt;/td&gt;
&lt;td&gt;410: disable the endpoint. 429, 502, 504: throttle&lt;/td&gt;
&lt;td&gt;Not stated&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Sources: &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/troubleshoot" rel="noopener noreferrer"&gt;Shopify troubleshooting&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/subscribe/https" rel="noopener noreferrer"&gt;Shopify HTTPS delivery&lt;/a&gt;, &lt;a href="https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries" rel="noopener noreferrer"&gt;GitHub failed deliveries&lt;/a&gt;, &lt;a href="https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks" rel="noopener noreferrer"&gt;GitHub best practices&lt;/a&gt;, &lt;a href="https://docs.slack.dev/apis/events-api/" rel="noopener noreferrer"&gt;Slack Events API&lt;/a&gt;, &lt;a href="https://developers.line.biz/en/docs/messaging-api/receiving-messages/" rel="noopener noreferrer"&gt;LINE receiving&lt;/a&gt;, &lt;a href="https://developers.line.biz/en/docs/messaging-api/check-webhook-error-statistics/" rel="noopener noreferrer"&gt;LINE error statistics&lt;/a&gt;, &lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks spec&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;A few details from those docs (timeouts are compared in &lt;a href="https://webhookadmin.com/en/blog/webhook-timeouts/" rel="noopener noreferrer"&gt;Webhook timeouts&lt;/a&gt;):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Slack disables event delivery for apps that fail too often.&lt;/strong&gt; If more than 95% of delivery attempts within 60 minutes hit a failure condition (certificate problems, responses slower than 3 seconds, more than 2 redirects, non-2xx), Slack turns off event subscriptions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Only Slack lets the receiver say "don't retry."&lt;/strong&gt; Add &lt;code&gt;x-slack-no-retry: 1&lt;/code&gt; to a non-2xx response.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Shopify deletes the subscription.&lt;/strong&gt; Subscriptions created through the Admin API are removed after 8 consecutive failures.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  4xx vs 5xx
&lt;/h2&gt;

&lt;p&gt;Many senders retry both, but returning the right class still helps: whoever reads the sender's delivery log can tell the two cases apart.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;4xx:&lt;/strong&gt; the request is the problem (bad signature, malformed body). Sending it again unchanged will probably fail again.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;5xx:&lt;/strong&gt; your side couldn't process it right now (database outage, dependency down). A later attempt will probably work.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If signature verification fails, don't process anything and return 400 or 401. If verification passes but processing fails before you've enqueued the work, return 5xx so the sender retries. Once the work is safely in your own queue, return 2xx and let your queue handle retries.&lt;/p&gt;

&lt;h2&gt;
  
  
  429 and Retry-After
&lt;/h2&gt;

&lt;p&gt;Returning 429 with &lt;code&gt;Retry-After&lt;/code&gt; when you're overloaded rarely helps. None of the senders in the table above documents honoring &lt;code&gt;Retry-After&lt;/code&gt;, and the Standard Webhooks spec only recommends throttling. The dependable way to handle load is to enqueue immediately and return 2xx.&lt;/p&gt;

&lt;h2&gt;
  
  
  Redirects, and the Google Apps Script 302
&lt;/h2&gt;

&lt;p&gt;Senders generally don't follow redirects. Stripe treats a 3xx as a failure and tells you to register the URL the redirect resolves to. The reason is simple: following a redirect would send the payload and signature somewhere the sender never validated. The Standard Webhooks spec also treats 3xx as a failure.&lt;/p&gt;

&lt;p&gt;If you receive webhooks in a Google Apps Script web app, senders may see a 302. Apps Script redirects Content service output to a one-time URL on &lt;code&gt;script.googleusercontent.com&lt;/code&gt; for security (&lt;a href="https://developers.google.com/apps-script/guides/content" rel="noopener noreferrer"&gt;Apps Script docs&lt;/a&gt;, checked on 2026-09-27). Your &lt;code&gt;doPost&lt;/code&gt; runs, but a sender that doesn't follow redirects records a failure and retries. If you stay on Apps Script, make the handler safe to run twice, or put a receiver in front that can return 2xx directly.&lt;/p&gt;

&lt;p&gt;The same thing happens with other receivers, for example &lt;a href="https://stackoverflow.com/questions/49848884/github-webhook-with-jenkins-return-302-found" rel="noopener noreferrer"&gt;GitHub webhooks to Jenkins returning 302&lt;/a&gt;. If a sender's log shows a 3xx, change the registered URL to the final destination.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to decide if you're the sender
&lt;/h2&gt;

&lt;p&gt;If your product sends webhooks, decide these four and put them in your receiver documentation:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Which codes count as success (2xx only is the norm)&lt;/li&gt;
&lt;li&gt;Whether you follow redirects (usually not)&lt;/li&gt;
&lt;li&gt;Whether 410 disables an endpoint or is retried like any other failure&lt;/li&gt;
&lt;li&gt;Whether you honor 429 and &lt;code&gt;Retry-After&lt;/code&gt;
&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Retry schedules are covered in &lt;a href="https://webhookadmin.com/en/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;designing webhook retries&lt;/a&gt;, and receiver timeouts in &lt;a href="https://webhookadmin.com/en/blog/webhook-timeouts/" rel="noopener noreferrer"&gt;webhook timeouts&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How Webhook Admin handles responses
&lt;/h2&gt;

&lt;p&gt;As of 2026-09-27:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Only 2xx is success.&lt;/li&gt;
&lt;li&gt;Redirects are not followed; a 3xx is a failure and is retried.&lt;/li&gt;
&lt;li&gt;410 is retried like any other failure. It doesn't disable the endpoint by itself; endpoints are disabled after five days of continuous failures.&lt;/li&gt;
&lt;li&gt;429 follows the normal retry schedule (immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h) and &lt;code&gt;Retry-After&lt;/code&gt; is not read. Instead, each endpoint gets at most 10 concurrent deliveries, and after 5 consecutive failures Webhook Admin pauses that endpoint for 30 seconds before trying one delivery.&lt;/li&gt;
&lt;li&gt;Responses time out after 15 seconds, and the first 1,024 bytes of the response body go into the delivery log.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The API's own error codes are listed under &lt;a href="https://webhookadmin.com/en/docs/api/#errors" rel="noopener noreferrer"&gt;errors&lt;/a&gt;. If you want a sender that records every status code and response body where your customers can see them, you can try Webhook Admin for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Should a webhook endpoint return 200 or 204?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Either. The major senders treat the whole 2xx range as success and don't distinguish between 200 and 204. If you include a body, keep it short, because senders often store it in their delivery log.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Does returning 410 Gone stop webhook deliveries?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;It depends on the sender. The Standard Webhooks spec recommends that senders disable an endpoint that returns 410, but many senders treat every non-2xx response the same and keep retrying. To stop deliveries for certain, delete or disable the endpoint in the sender's dashboard or API.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why does my Google Apps Script webhook return 302?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Content returned by Apps Script's Content service is redirected to a one-time URL on script.googleusercontent.com for security. Most webhook senders don't follow redirects and record the 302 as a failure, even though your doPost already ran.&lt;/p&gt;




&lt;p&gt;Thanks for reading! What status does your handler return when a signature doesn't match? Tell us in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/webhook-response-status-codes/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>api</category>
      <category>http</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Stripe Webhooks: Retries, Ordering, Duplicates, Timeouts, and IPs</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Sat, 24 Oct 2026 13:17:56 +0000</pubDate>
      <link>https://dev.to/shannonllc/stripe-webhooks-retries-ordering-duplicates-timeouts-and-ips-46f0</link>
      <guid>https://dev.to/shannonllc/stripe-webhooks-retries-ordering-duplicates-timeouts-and-ips-46f0</guid>
      <description>&lt;p&gt;Stripe retries for up to three days, doesn't guarantee order, and can deliver the same event twice. We put retries, ordering, duplicates, timeouts and source IPs in one table, each linked to Stripe's docs, and show how to build a receiver around them.&lt;/p&gt;

&lt;p&gt;In live mode, Stripe retries webhook deliveries for up to three days using exponential backoff. In a sandbox, it retries three times over a few hours. Stripe does not guarantee that events arrive in the order they were created, and the same event can arrive more than once, so your receiver has to deduplicate on the event ID and, when order matters, fetch the current state from the API.&lt;/p&gt;

&lt;p&gt;These details are spread across several pages of Stripe's docs. This post collects them in one table, checked against the official documentation on 2026-09-27, and marks anything Stripe doesn't publish as "not stated."&lt;/p&gt;

&lt;h2&gt;
  
  
  Stripe webhook behavior at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Topic&lt;/th&gt;
&lt;th&gt;Behavior&lt;/th&gt;
&lt;th&gt;Source&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Automatic retries (live)&lt;/td&gt;
&lt;td&gt;Exponential backoff for up to 3 days&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Automatic retries (sandbox)&lt;/td&gt;
&lt;td&gt;3 times over a few hours&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Individual intervals&lt;/td&gt;
&lt;td&gt;Not stated; the Dashboard shows the next scheduled attempt&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Endpoint disabled or deleted during retries&lt;/td&gt;
&lt;td&gt;No further retries for that event; if you disable and re-enable before the next attempt, retries continue&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Manual resend&lt;/td&gt;
&lt;td&gt;Dashboard: up to 15 days after the event was created. CLI (&lt;code&gt;stripe events resend&lt;/code&gt;): up to 30 days&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Effect of a manual resend&lt;/td&gt;
&lt;td&gt;A 2xx on a manual resend does not cancel automatic retries&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Finding undelivered events&lt;/td&gt;
&lt;td&gt;List Events with &lt;code&gt;delivery_success=false&lt;/code&gt;; only events from the last 30 days&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/webhooks/process-undelivered-events" rel="noopener noreferrer"&gt;Process undelivered events&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ordering&lt;/td&gt;
&lt;td&gt;Not guaranteed&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Duplicates&lt;/td&gt;
&lt;td&gt;The same event can be delivered more than once&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Timeout&lt;/td&gt;
&lt;td&gt;No number of seconds stated; timeouts count as failures&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Success&lt;/td&gt;
&lt;td&gt;2xx; redirects (3xx) are treated as failures&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TLS&lt;/td&gt;
&lt;td&gt;TLS 1.2 and 1.3&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Signature&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Stripe-Signature&lt;/code&gt; with &lt;code&gt;t=&lt;/code&gt; and &lt;code&gt;v1=&lt;/code&gt;, HMAC-SHA256; a new timestamp and signature on every attempt&lt;/td&gt;
&lt;td&gt;Same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Source IPs&lt;/td&gt;
&lt;td&gt;Published list, also as &lt;code&gt;ips_webhooks.json&lt;/code&gt; and &lt;code&gt;.txt&lt;/code&gt;; changes announced on a mailing list 7 days ahead&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/ips" rel="noopener noreferrer"&gt;IP addresses&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Failure notification&lt;/td&gt;
&lt;td&gt;In live mode Stripe emails you when webhooks are failing&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/billing/subscriptions/webhooks" rel="noopener noreferrer"&gt;Subscriptions and webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Endpoints per account&lt;/td&gt;
&lt;td&gt;Up to 16&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Some third-party write-ups state specific numbers, such as "about 16 retries" or "a 20-second timeout." We could not find either in Stripe's official docs as of 2026-09-27. If your design depends on them, confirm the real behavior in your Dashboard's delivery log.&lt;/p&gt;

&lt;h2&gt;
  
  
  Retry behavior that catches people out
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Processing an event yourself doesn't stop retries
&lt;/h3&gt;

&lt;p&gt;After an outage you might list undelivered events and process them yourself. Stripe still considers them undelivered and keeps retrying. Stripe's guide says to detect events you've already handled, skip them and return a success response, which stops further retries. Your backfill script and Stripe's retries can run at the same time, so track "processing" as well as "processed."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Express. Keep the body raw and verify before using it.&lt;/span&gt;
&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/webhooks/stripe&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}),&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="na"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;stripe-signature&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;endpointSecret&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Only the first delivery of an event ID gets through (unique constraint)&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;inserted&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;INSERT INTO stripe_events (id, status) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;processing&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;inserted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;rowCount&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="c1"&gt;// in progress or done&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;stripe-event&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt; &lt;span class="c1"&gt;// heavy work happens in the worker&lt;/span&gt;
  &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Pausing your endpoint can drop events
&lt;/h3&gt;

&lt;p&gt;If a scheduled retry comes due while your endpoint is disabled, Stripe stops retrying that event. If you disable the endpoint for maintenance, run List Events with &lt;code&gt;delivery_success=false&lt;/code&gt; after you re-enable it. The &lt;a href="https://webhookadmin.com/en/blog/recover-missed-webhooks/" rel="noopener noreferrer"&gt;recovering missed webhooks&lt;/a&gt; post covers reconciliation in detail.&lt;/p&gt;

&lt;h3&gt;
  
  
  Sandboxes can't show you day-three behavior
&lt;/h3&gt;

&lt;p&gt;Three retries over a few hours means you'll never see, in a sandbox, a burst of days-old events arriving after a long outage. Test your deduplication and ordering logic by replaying events locally.&lt;/p&gt;

&lt;h2&gt;
  
  
  Ordering and duplicates
&lt;/h2&gt;

&lt;p&gt;Stripe's docs use subscription creation as an example: it can produce &lt;code&gt;customer.subscription.created&lt;/code&gt;, &lt;code&gt;invoice.created&lt;/code&gt;, &lt;code&gt;invoice.paid&lt;/code&gt; and &lt;code&gt;charge.created&lt;/code&gt;, and Stripe doesn't guarantee they arrive in that order. Snapshot events record &lt;code&gt;created&lt;/code&gt; in seconds, so different events can share a timestamp. Stripe says not to use &lt;code&gt;created&lt;/code&gt; to order events or to decide whether you've processed one; track the event ID instead.&lt;/p&gt;

&lt;p&gt;Three rules cover it:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Deduplicate on the event ID.&lt;/strong&gt; Record processed IDs under a unique constraint and skip any that are already there.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fetch state from the API.&lt;/strong&gt; If &lt;code&gt;invoice.paid&lt;/code&gt; arrives first, use the IDs inside it to retrieve the invoice, charge and subscription instead of waiting for the earlier events.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Two separate events can describe the same change.&lt;/strong&gt; Stripe notes that in some cases two Event objects are generated and sent separately; identify those by the &lt;code&gt;data.object&lt;/code&gt; ID together with &lt;code&gt;event.type&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;We go deeper in &lt;a href="https://webhookadmin.com/en/blog/webhook-idempotency-duplicates/" rel="noopener noreferrer"&gt;handling duplicate webhooks&lt;/a&gt; and &lt;a href="https://webhookadmin.com/en/blog/webhook-out-of-order-events/" rel="noopener noreferrer"&gt;out-of-order webhooks&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Return 2xx before the heavy work
&lt;/h2&gt;

&lt;p&gt;Stripe asks you to return a 2xx quickly, before any complex logic that could cause a timeout, for example before marking an invoice as paid in your accounting system. With no published timeout, keep the handler to "verify, record, enqueue, 200." Stripe also recommends processing events from an asynchronous queue so that spikes (such as the start of a month, when many subscriptions renew) don't overwhelm your server.&lt;/p&gt;

&lt;h2&gt;
  
  
  Allowlisting Stripe's IPs
&lt;/h2&gt;

&lt;p&gt;Stripe publishes the IPs it sends webhooks from, also available at &lt;code&gt;https://stripe.com/files/ips/ips_webhooks.json&lt;/code&gt; and &lt;code&gt;.txt&lt;/code&gt;, and announces changes on its API announcements mailing list 7 days in advance. Stripe recommends using both an IP allowlist and signature verification. If you filter by IP, keep verifying signatures and refresh the list on a schedule. Our &lt;a href="https://webhookadmin.com/en/blog/webhook-static-ip/" rel="noopener noreferrer"&gt;static IP post&lt;/a&gt; covers IP-based filtering more broadly.&lt;/p&gt;

&lt;h2&gt;
  
  
  When you are the one sending
&lt;/h2&gt;

&lt;p&gt;Stripe's webhooks are a good reference if your own product needs to send them: a defined retry window with exponential backoff, a visible delivery log with the next attempt, manual resends, email when deliveries keep failing, and a fresh signature on every attempt. We covered choosing a schedule in &lt;a href="https://webhookadmin.com/en/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;designing webhook retries&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Webhook Admin handles retries, logs and alerts through an API. By default it retries immediately, then after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h (8 attempts, about 28 hours; you can choose the number of retries and the interval per endpoint), logs the status code and the first 1,024 bytes of every response, and lets you retry deliveries from the dashboard or the API. It alerts you (Slack, Teams, email or a webhook) when an endpoint has been failing for an hour, when retries run out, and when it disables an endpoint after five days of failures. The free plan includes 50,000 messages a month: &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;How do I stop Stripe from retrying a webhook?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Return a 2xx for it. Processing the event yourself, or a manual resend that returns 2xx, does not cancel Stripe's automatic retries, so when an already-processed event arrives, skip the work and return 2xx. If you disable or delete the endpoint while retries are pending, Stripe stops retrying that event.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What is Stripe's webhook retry interval?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Stripe documents exponential backoff for up to three days in live mode but does not list the individual intervals. The Event deliveries tab for your endpoint shows when the next retry is scheduled.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do sandbox webhooks retry the same way as live mode?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;No. Events created in a sandbox are retried three times over a few hours, so you cannot reproduce live mode's multi-day retries there. Test deduplication and ordering by replaying events locally.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Which of these Stripe behaviors caused you the most trouble in production? We'd love to hear in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/en/blog/stripe-webhooks-retries-order-duplicates/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>stripe</category>
      <category>api</category>
      <category>webdev</category>
    </item>
    <item>
      <title>How to Test Webhooks Locally: Tunnels, Provider CLIs, and Replays</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Tue, 20 Oct 2026 13:17:42 +0000</pubDate>
      <link>https://dev.to/shannonllc/how-to-test-webhooks-locally-tunnels-provider-clis-and-replays-4kpd</link>
      <guid>https://dev.to/shannonllc/how-to-test-webhooks-locally-tunnels-provider-clis-and-replays-4kpd</guid>
      <description>&lt;p&gt;Your handler runs on localhost, but the webhook sender needs a public URL. We compare three ways to get webhooks onto your machine: tunnels like ngrok or cloudflared, provider CLIs like stripe listen, and replaying saved payloads.&lt;/p&gt;

&lt;p&gt;There are three practical ways to receive webhooks on your development machine. You can open a tunnel so your local server gets a public URL and the real sender delivers to it. You can use the provider's CLI to forward its events to localhost. Or you can save a payload once and replay it, re-signed, as often as you like. This post compares the three, covers what changes when signatures are involved, and lists what to close when you're done.&lt;/p&gt;

&lt;h2&gt;
  
  
  The three methods at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Method&lt;/th&gt;
&lt;th&gt;Examples&lt;/th&gt;
&lt;th&gt;Best for&lt;/th&gt;
&lt;th&gt;URL&lt;/th&gt;
&lt;th&gt;Signature&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Tunnel&lt;/td&gt;
&lt;td&gt;ngrok, cloudflared&lt;/td&gt;
&lt;td&gt;End-to-end tests from the real sender&lt;/td&gt;
&lt;td&gt;Public https URL&lt;/td&gt;
&lt;td&gt;Signed with the sender's real secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Provider CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;stripe listen&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Quick tests of one provider&lt;/td&gt;
&lt;td&gt;None needed&lt;/td&gt;
&lt;td&gt;Signed with a CLI-specific secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Replay&lt;/td&gt;
&lt;td&gt;curl, a small script&lt;/td&gt;
&lt;td&gt;Repeatable input, automated tests&lt;/td&gt;
&lt;td&gt;None needed&lt;/td&gt;
&lt;td&gt;You re-sign locally&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;If you only want to look at what a sender posts, without running your own server, request inspectors such as webhook.site do that; see &lt;a href="https://webhookadmin.com/blog/webhook-inspection-tools/" rel="noopener noreferrer"&gt;webhook inspection tools compared&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Method 1: a tunnel
&lt;/h2&gt;

&lt;p&gt;A tunnel exposes a local port through a public URL. Register that URL with the sender and real webhooks arrive at your local server.&lt;/p&gt;

&lt;h3&gt;
  
  
  ngrok
&lt;/h3&gt;

&lt;p&gt;Free plan limits, checked on 2026-09-27 on &lt;a href="https://ngrok.com/pricing" rel="noopener noreferrer"&gt;ngrok's pricing page&lt;/a&gt; and &lt;a href="https://ngrok.com/docs/pricing-limits/free-plan-limits" rel="noopener noreferrer"&gt;free plan limits&lt;/a&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Item&lt;/th&gt;
&lt;th&gt;Free plan&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Online endpoints&lt;/td&gt;
&lt;td&gt;Up to 3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Domain&lt;/td&gt;
&lt;td&gt;One assigned dev domain (&lt;code&gt;…ngrok-free.app&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Data transfer&lt;/td&gt;
&lt;td&gt;1 GB per month&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP requests&lt;/td&gt;
&lt;td&gt;20,000 per month&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Interstitial page&lt;/td&gt;
&lt;td&gt;Shown before HTML browser traffic; ngrok says it does not affect APIs or programmatic access&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Because the dev domain stays the same, you register it with the sender once and it keeps working across restarts. The first paid plan (Hobbyist) is $10 a month.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ngrok http 3000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  cloudflared Quick Tunnels
&lt;/h3&gt;

&lt;p&gt;Cloudflare's Quick Tunnels need no account (&lt;a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/" rel="noopener noreferrer"&gt;Cloudflare docs&lt;/a&gt;, checked on 2026-09-27):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cloudflared tunnel &lt;span class="nt"&gt;--url&lt;/span&gt; http://localhost:3000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each run gets a random &lt;code&gt;trycloudflare.com&lt;/code&gt; subdomain, so you update the URL at the sender every time. The docs list a limit of 200 in-flight requests (beyond that you get 429s), no Server-Sent Events, and describe Quick Tunnels as intended for testing and development only.&lt;/p&gt;

&lt;h2&gt;
  
  
  Method 2: the provider's CLI
&lt;/h2&gt;

&lt;p&gt;With Stripe, &lt;code&gt;stripe listen&lt;/code&gt; forwards your account's events to a local URL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;stripe listen &lt;span class="nt"&gt;--forward-to&lt;/span&gt; localhost:3000/webhooks/stripe
&lt;span class="c"&gt;# in another terminal&lt;/span&gt;
stripe trigger payment_intent.succeeded
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;stripe listen&lt;/code&gt; prints a signing secret (&lt;code&gt;whsec_…&lt;/code&gt;) when it starts, and the events it forwards are signed with that secret, not with the secret of any endpoint you created in the Dashboard. Stripe's troubleshooting page specifically warns about mixing the two up (&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe webhooks&lt;/a&gt;, &lt;a href="https://docs.stripe.com/webhooks/signature" rel="noopener noreferrer"&gt;signature troubleshooting&lt;/a&gt;, checked on 2026-09-27). Keep the CLI secret in your local environment and the endpoint secret in production.&lt;/p&gt;

&lt;p&gt;A CLI works on networks where you can't open a tunnel. What it doesn't exercise is the real path from the sender to your server: TLS, your load balancer, reachability from the internet.&lt;/p&gt;

&lt;h2&gt;
  
  
  Method 3: replay a saved payload
&lt;/h2&gt;

&lt;p&gt;For repeatable tests, save one real payload and its headers, then send it to your local server again. If the scheme signs a timestamp, the saved signature stops verifying after the tolerance window (often five minutes), so re-sign with the current time.&lt;/p&gt;

&lt;p&gt;For Standard Webhooks (which Webhook Admin uses), &lt;code&gt;Webhook.sign&lt;/code&gt; from the &lt;code&gt;webhookadmin&lt;/code&gt; npm package produces the header:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;readFileSync&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:fs&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhookadmin&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;secret&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// a local test whsec_…&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;readFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;saved-body.json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;utf8&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// exactly as received&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;msg_local_test_1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;signature&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;secret&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;sign&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;http://localhost:3000/webhooks&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;POST&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;content-type&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-timestamp&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ts&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-signature&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Send it twice with the same &lt;code&gt;webhook-id&lt;/code&gt; and you are also testing your duplicate handling. The same script drops straight into an automated test; &lt;a href="https://webhookadmin.com/blog/test-webhook-handlers/" rel="noopener noreferrer"&gt;testing webhook handlers&lt;/a&gt; covers that in depth.&lt;/p&gt;

&lt;h2&gt;
  
  
  Signatures through a tunnel
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A tunnel doesn't change the body.&lt;/strong&gt; If verification fails through a tunnel, the cause is how your handler reads the body or which secret it uses. The &lt;a href="https://webhookadmin.com/blog/webhook-signature-verification-failed/" rel="noopener noreferrer"&gt;signature troubleshooting guide&lt;/a&gt; walks through it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;URL-signing schemes sign the tunnel URL.&lt;/strong&gt; Twilio signs the URL configured in Twilio plus the parameters. If your handler validates against the URL it sees locally (&lt;code&gt;http://localhost:3000/…&lt;/code&gt;), it won't match. Validate against the public tunnel URL.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use separate secrets.&lt;/strong&gt; Different secrets and differently named environment variables for local, test and production cut down on mix-ups.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The exposure risk, and how to close up
&lt;/h2&gt;

&lt;p&gt;While a tunnel is open, anyone who knows the URL can send requests to your machine. With a stable URL such as an ngrok dev domain, whoever had it last time can reach you again next time you open it.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Keep signature verification on locally. Never open a tunnel with verification disabled.&lt;/li&gt;
&lt;li&gt;Run a server that only serves the webhook route. Don't expose admin or debug routes on the same port.&lt;/li&gt;
&lt;li&gt;Stop the tunnel process when you're done.&lt;/li&gt;
&lt;li&gt;Remove the tunnel URL from the sender, or pause that endpoint. Otherwise the sender keeps retrying and recording failures.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Testing with Webhook Admin as the sender
&lt;/h2&gt;

&lt;p&gt;Webhook Admin gives every project a live and a test environment, and messages sent in the test environment don't count toward your monthly volume. Endpoint URLs must be https in both environments, so for local testing you register the tunnel's https URL.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;With a test API key (&lt;code&gt;sk_test_…&lt;/code&gt;), register the tunnel URL as an endpoint.&lt;/li&gt;
&lt;li&gt;Send a test message to just that endpoint with &lt;code&gt;POST /v1/endpoints/{id}/test&lt;/code&gt; (event type &lt;code&gt;webhook.test&lt;/code&gt; by default). Test sends don't count toward usage.&lt;/li&gt;
&lt;li&gt;Verify it locally with &lt;code&gt;verify&lt;/code&gt; from the &lt;code&gt;webhookadmin&lt;/code&gt; package.&lt;/li&gt;
&lt;li&gt;If it fails, open the delivery log to see the status code and the first 1,024 bytes of your response, fix the handler, and replay the delivery (&lt;code&gt;POST /v1/deliveries/{id}/retry&lt;/code&gt;).&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;When the tunnel URL changes, as it does with Quick Tunnels, &lt;a href="https://webhookadmin.com/docs/api/#update-endpoint" rel="noopener noreferrer"&gt;update the endpoint&lt;/a&gt; with the new URL. A replayed delivery keeps the same &lt;code&gt;webhook-id&lt;/code&gt;, so the same loop tests your deduplication. For keeping keys, endpoints and data apart between test and live, see &lt;a href="https://webhookadmin.com/blog/webhook-test-environments/" rel="noopener noreferrer"&gt;separating test and live webhooks&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you're building the sending side and want to fire test webhooks at your local receiver, you can sign up for Webhook Admin for free (test-environment messages aren't counted): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Can I test webhooks without ngrok?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes. Cloudflare Quick Tunnels (cloudflared tunnel --url) give you a temporary https URL without an account. For Stripe, stripe listen forwards events without any public URL. And replaying a saved payload, re-signed locally, needs no external service at all.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The free ngrok URL keeps changing. What can I do?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;As of 2026-09-27, ngrok's free plan assigns each account one dev domain that stays the same, so you register it once. If you don't need a stable URL, cloudflared Quick Tunnels give you a new random one each run.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How do I resend a webhook I already received?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Use the sender's replay feature if it has one (stripe events resend for Stripe, redelivery in the UI or API for GitHub). For repeated local runs, save the raw body, re-sign it with the current timestamp and POST it with curl or a script.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Which setup do you use for local webhook development? We'd love to hear in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/blog/test-webhooks-locally/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>testing</category>
      <category>webdev</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>How to Send Webhooks: Every Part You Have to Build</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Thu, 15 Oct 2026 13:17:29 +0000</pubDate>
      <link>https://dev.to/shannonllc/how-to-send-webhooks-every-part-you-have-to-build-2mn</link>
      <guid>https://dev.to/shannonllc/how-to-send-webhooks-every-part-you-have-to-build-2mn</guid>
      <description>&lt;p&gt;Sending one webhook is a single POST request. Sending them to customers in production takes eleven parts, so we listed each one, the decisions behind it, and a minimal Node.js sender to start from.&lt;/p&gt;

&lt;p&gt;Sending a webhook is one HTTP POST. Sending webhooks to customers in production is a small system: you need to retry what didn't arrive, sign what you send, record what happened, and stop hammering endpoints that are gone. This post lists every part you end up building, what to decide for each, and a minimal Node.js sender you can start from.&lt;/p&gt;

&lt;h2&gt;
  
  
  The parts
&lt;/h2&gt;

&lt;p&gt;A webhook sender that customers can rely on has these eleven pieces:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Endpoint registration and URL validation.&lt;/strong&gt; Customers register URLs and pick event types. Validation includes SSRF checks so nobody can point you at your own network.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Event types.&lt;/strong&gt; Names like &lt;code&gt;invoice.paid&lt;/code&gt; and the catalog of them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Payload shape.&lt;/strong&gt; How the type, timestamp and data are laid out.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Signing.&lt;/strong&gt; An HMAC (or public-key) signature so receivers can verify the sender.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A queue and retries.&lt;/strong&gt; Decouple sending from your business logic and retry failures with growing delays.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Timeouts and success rules.&lt;/strong&gt; How long to wait and which responses count as delivered.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Delivery logs.&lt;/strong&gt; Status code, response snippet, duration and errors for every attempt.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Failure alerts.&lt;/strong&gt; Tell your team, and the endpoint's owner, when deliveries keep failing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Auto-disable and re-enable.&lt;/strong&gt; Stop sending to endpoints that have failed for days, and let them come back.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Secret rotation.&lt;/strong&gt; Replace a signing secret without breaking receivers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A customer portal.&lt;/strong&gt; Let customers manage endpoints, read logs and replay deliveries themselves.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Registration and URL validation
&lt;/h2&gt;

&lt;p&gt;Model endpoints as customer plus URL, with an optional list of event types per URL. At registration, at minimum: accept only &lt;code&gt;https&lt;/code&gt;, reject credentials in the URL (&lt;code&gt;user:pass@&lt;/code&gt;), reject IP-literal hosts, and reject internal names such as &lt;code&gt;localhost&lt;/code&gt; or &lt;code&gt;*.internal&lt;/code&gt;. Then check again right before each send that the hostname doesn't resolve to a private address, because DNS answers can change after registration. The &lt;a href="https://webhookadmin.com/blog/webhook-ssrf-protection/" rel="noopener noreferrer"&gt;SSRF post&lt;/a&gt; goes through the full list.&lt;/p&gt;

&lt;h2&gt;
  
  
  Event types and payload shape
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;resource.action&lt;/code&gt; names (&lt;code&gt;invoice.paid&lt;/code&gt;, &lt;code&gt;customer.deleted&lt;/code&gt;) let receivers route by prefix. For the body, a type/timestamp/data envelope is easy to consume, and it is what the &lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks spec&lt;/a&gt; recommends. The same spec suggests keeping payloads small, usually under 20 KB.&lt;/p&gt;

&lt;h2&gt;
  
  
  Signing
&lt;/h2&gt;

&lt;p&gt;Use a scheme receivers already have libraries for rather than inventing one. Standard Webhooks defines:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Three headers: &lt;code&gt;webhook-id&lt;/code&gt;, &lt;code&gt;webhook-timestamp&lt;/code&gt;, &lt;code&gt;webhook-signature&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Signed content &lt;code&gt;id.timestamp.body&lt;/code&gt;, HMAC-SHA256, base64&lt;/li&gt;
&lt;li&gt;A secret written as &lt;code&gt;whsec_&lt;/code&gt; plus base64 random bytes (the spec recommends 24 to 64 bytes)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The ID is signed so nobody can change the value receivers deduplicate on. The timestamp is signed so an old captured request can't be replayed later. &lt;a href="https://webhookadmin.com/blog/standard-webhooks-explained/" rel="noopener noreferrer"&gt;Standard Webhooks explained&lt;/a&gt; goes through the reasoning behind each field.&lt;/p&gt;

&lt;h2&gt;
  
  
  Queue and retries
&lt;/h2&gt;

&lt;p&gt;Sending inside the request that created the event makes your code wait on the customer's server, and loses the event if that server is down. Write the event, enqueue it, and let a worker send. If you write the business row and the event row in the same database transaction (the transactional outbox pattern), you also avoid "saved the order, never emitted the event" (&lt;a href="https://webhookadmin.com/blog/webhook-outbox-pattern/" rel="noopener noreferrer"&gt;the outbox pattern&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;Retry with short delays first and longer ones as failures continue. We covered schedules, jitter and when to give up in &lt;a href="https://webhookadmin.com/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;designing webhook retries&lt;/a&gt;. Keep &lt;code&gt;webhook-id&lt;/code&gt; the same across retries; regenerate the timestamp and signature on every attempt.&lt;/p&gt;

&lt;h2&gt;
  
  
  Timeouts and what counts as success
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Timeout:&lt;/strong&gt; 10 to 15 seconds is typical. GitHub gives receivers 10 seconds and Shopify 5 (checked on 2026-09-27 in &lt;a href="https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries" rel="noopener noreferrer"&gt;GitHub's&lt;/a&gt; and &lt;a href="https://shopify.dev/docs/apps/build/webhooks/troubleshoot" rel="noopener noreferrer"&gt;Shopify's&lt;/a&gt; docs). Longer timeouts let slow endpoints tie up your workers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Success:&lt;/strong&gt; 2xx only.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Redirects:&lt;/strong&gt; Don't follow them. Following a redirect sends the payload somewhere you never validated.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  A minimal sender in Node.js
&lt;/h2&gt;

&lt;p&gt;One attempt: sign, send, stop after 15 seconds, don't follow redirects. Uses the built-in &lt;code&gt;fetch&lt;/code&gt; (Node 18+) and &lt;code&gt;AbortSignal.timeout&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;randomUUID&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:crypto&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;SECRET&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;ENDPOINT_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/^whsec_/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;''&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;sendOnce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;msgId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;timestamp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;toISOString&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toString&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;SECRET&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;msgId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;.&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;ts&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;.&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;digest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;started&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;POST&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;content-type&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;msgId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-timestamp&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;ts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhook-signature&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`v1,&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;sig&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;},&lt;/span&gt;
      &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;manual&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// return 3xx as is instead of following it&lt;/span&gt;
      &lt;span class="na"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AbortSignal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;15&lt;/span&gt;&lt;span class="nx"&gt;_000&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="c1"&gt;// aborts with a TimeoutError&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;head&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;()).&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1024&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;head&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;ms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;started&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;head&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;ms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;started&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// One ID per event, reused on every retry&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;msgId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;`msg_&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nf"&gt;randomUUID&lt;/span&gt;&lt;span class="p"&gt;()}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;AbortSignal.timeout()&lt;/code&gt; returns a signal that aborts with a &lt;code&gt;TimeoutError&lt;/code&gt; after the given time (&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static" rel="noopener noreferrer"&gt;MDN&lt;/a&gt;). With &lt;code&gt;redirect: 'manual'&lt;/code&gt;, Node's &lt;code&gt;fetch&lt;/code&gt; hands you the 3xx response itself, so &lt;code&gt;res.ok&lt;/code&gt; is false and the attempt counts as failed. The caller logs the result and, on failure, schedules the next attempt.&lt;/p&gt;

&lt;h2&gt;
  
  
  Delivery logs
&lt;/h2&gt;

&lt;p&gt;Log every attempt. These records answer support tickets and let you show a customer exactly what their server returned.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Event ID, type, endpoint&lt;/td&gt;
&lt;td&gt;What went where&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Attempt number and time&lt;/td&gt;
&lt;td&gt;Retry history&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code and first ~1 KB of the response&lt;/td&gt;
&lt;td&gt;The receiver's error message&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Duration and connection errors&lt;/td&gt;
&lt;td&gt;Timeouts, DNS and TLS failures&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The payload&lt;/td&gt;
&lt;td&gt;Replays&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Set a retention period and delete old records, shorter if payloads contain personal data. &lt;a href="https://webhookadmin.com/blog/webhook-delivery-logs/" rel="noopener noreferrer"&gt;What to log for outgoing webhooks&lt;/a&gt; goes deeper.&lt;/p&gt;

&lt;h2&gt;
  
  
  Alerts and auto-disabling
&lt;/h2&gt;

&lt;p&gt;An endpoint that keeps failing costs a worker slot on every retry. Handle it in two stages: pause briefly after a burst of consecutive failures, and disable the endpoint after failures have lasted days. Tell both your team and the endpoint's owner when you disable it; Stripe, for example, emails account owners when webhook deliveries keep failing (&lt;a href="https://docs.stripe.com/billing/subscriptions/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  Secret rotation
&lt;/h2&gt;

&lt;p&gt;Customers will need to replace secrets, after a leak or on a schedule. Receivers can't switch at the same instant you do, so for a period sign with both the old and new secret and put both signatures in &lt;code&gt;webhook-signature&lt;/code&gt;, separated by a space. Stripe lets the old secret stay active for up to 24 hours (&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  Customer portal
&lt;/h2&gt;

&lt;p&gt;As your customer count grows, so do "please change our URL" and "we didn't get the event" tickets. A page where customers register endpoints, read their delivery logs and replay failures removes most of them. If you embed it in your own app, issue short-lived, per-customer links so no customer can see another's data.&lt;/p&gt;

&lt;h2&gt;
  
  
  Build order
&lt;/h2&gt;

&lt;p&gt;You don't have to ship everything at once:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Signing, queued retries, delivery logs&lt;/li&gt;
&lt;li&gt;Timeouts, redirect handling, URL validation&lt;/li&gt;
&lt;li&gt;Failure alerts and auto-disabling&lt;/li&gt;
&lt;li&gt;Secret rotation and the customer portal&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Where Webhook Admin fits
&lt;/h2&gt;

&lt;p&gt;Webhook Admin covers parts 1 and 4 through 11 behind an API and a dashboard. You decide the event types and payloads, then call &lt;code&gt;POST /v1/messages&lt;/code&gt; with the customer ID, event type and payload.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Endpoint URLs must be &lt;code&gt;https&lt;/code&gt; on port 443 or 8443. IP-literal hosts, internal names and names that resolve to private addresses are rejected, and redirects are never followed.&lt;/li&gt;
&lt;li&gt;Signatures follow Standard Webhooks; after a rotation, messages carry both signatures for 24 hours.&lt;/li&gt;
&lt;li&gt;Retries: by default immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h (8 attempts, about 28 hours); you can choose the number of retries and the interval per endpoint. The timeout is 15 seconds.&lt;/li&gt;
&lt;li&gt;Every attempt is logged with the status code, the first 1,024 bytes of the response and the duration, and can be replayed from the dashboard or the API.&lt;/li&gt;
&lt;li&gt;Endpoints that fail for five days are disabled automatically, with alerts to Slack, Microsoft Teams, email, a webhook or Chatwork.&lt;/li&gt;
&lt;li&gt;The customer portal is available from the Starter plan.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The &lt;a href="https://webhookadmin.com/docs/" rel="noopener noreferrer"&gt;getting started guide&lt;/a&gt; walks through the setup and &lt;a href="https://webhookadmin.com/#pricing" rel="noopener noreferrer"&gt;pricing&lt;/a&gt; lists the plans. If you'd rather not build the retry, logging and alerting parts yourself, you can sign up for free (50,000 messages a month): &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Which queue should I use?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Whatever you already run. SQS, Cloud Tasks, Sidekiq or BullMQ all work, as long as they can delay a job and run it again on failure. You still need your own per-endpoint failure tracking and a way to replay deliveries after the queue gives up.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can't I just send the webhook synchronously in the request handler?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If the customer's endpoint is slow, your own request waits for it, and if it is down the event is lost. Record the event in your transaction and let a worker send it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What should I build first?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Signatures, queued retries and a delivery log. Without signatures receivers cannot trust you, without retries a short outage on their side drops events, and without logs you cannot answer "did you send it?"&lt;/p&gt;




&lt;p&gt;Thanks for reading! Which of these parts took your team the longest to get right? We'd love to hear in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/blog/how-to-send-webhooks/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>api</category>
      <category>node</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Why Webhook Signature Verification Fails: Raw Body, Wrong Secret, Clock Skew, Proxies</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Mon, 12 Oct 2026 13:17:58 +0000</pubDate>
      <link>https://dev.to/shannonllc/why-webhook-signature-verification-fails-raw-body-wrong-secret-clock-skew-proxies-196f</link>
      <guid>https://dev.to/shannonllc/why-webhook-signature-verification-fails-raw-body-wrong-secret-clock-skew-proxies-196f</guid>
      <description>&lt;p&gt;Your webhook signature check fails, and the secret looks right. We list the causes in the order you're likely to hit them, from the raw body and hex vs base64 to clock skew and proxies, plus a step-by-step way to find where it breaks.&lt;/p&gt;

&lt;p&gt;When webhook signature verification fails, check one thing first: are you computing the HMAC over the exact bytes that arrived? If your framework parsed the body into JSON and you turned it back into a string, the content is the same but the bytes are not, and the signature will never match. This post lists the causes in the order you are likely to hit them, gives a step-by-step way to find where your calculation diverges, and compares how the major providers sign their webhooks.&lt;/p&gt;

&lt;h2&gt;
  
  
  The usual causes, most common first
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The body was parsed before you verified it.&lt;/strong&gt; &lt;code&gt;express.json()&lt;/code&gt;, the Next.js Pages Router body parser, or a FastAPI handler that takes a Pydantic model all hand you a parsed object. Serializing it again changes whitespace, key order or escaping.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Wrong secret.&lt;/strong&gt; Test vs live, one endpoint's secret vs another's, or the temporary secret a CLI printed. Stripe's own troubleshooting page says the most common error is using the wrong endpoint secret (&lt;a href="https://docs.stripe.com/webhooks/signature" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Wrong encoding.&lt;/strong&gt; You output hex where the provider sends base64, or the reverse. Some schemes also base64-encode the secret itself (Standard Webhooks' &lt;code&gt;whsec_…&lt;/code&gt;), and you must decode it before use.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Clock skew.&lt;/strong&gt; Schemes that sign a timestamp reject requests outside a tolerance window, typically five minutes. A server with a drifting clock fails intermittently.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The URL changed.&lt;/strong&gt; Twilio signs the URL. A proxy that terminates TLS can turn &lt;code&gt;https&lt;/code&gt; into &lt;code&gt;http&lt;/code&gt; or add a port, and the signature no longer matches.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Right after a secret rotation.&lt;/strong&gt; The sender switched to a new secret and the receiver still only checks the old one.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Find the mismatch step by step
&lt;/h2&gt;

&lt;p&gt;Guessing wastes time. Capture what arrived and redo the math.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Log the raw body and headers.&lt;/strong&gt; Before verification, write the received bytes somewhere. Base64-encode the body when you log it so line endings and encodings survive.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Confirm the secret.&lt;/strong&gt; Print the first and last few characters of the secret your code loaded and compare them with the provider's dashboard. Look for stray whitespace or a trailing newline from the environment file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Recompute locally.&lt;/strong&gt; Using the logged body and the secret, compute the HMAC exactly as the provider documents. If it matches the header, your handler is modifying the body.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If it doesn't match, recheck what is signed.&lt;/strong&gt; Is there a timestamp or an ID in front of the body? Is the URL part of it? Which separator? Use the table below and the provider's docs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check the clock and the tolerance.&lt;/strong&gt; Make sure the server syncs with NTP and that you haven't set a tolerance of zero.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For step 3, a GitHub-style check looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;createHmac&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:crypto&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;readFileSync&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:fs&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;readFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;body.b64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;utf8&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// the logged raw body&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;expected&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256=&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nf"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;GITHUB_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;digest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;hex&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// compare with the X-Hub-Signature-256 you received&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;GitHub publishes a test vector you can use to check your function: with the secret &lt;code&gt;It's a Secret to Everybody&lt;/code&gt; and the payload &lt;code&gt;Hello, World!&lt;/code&gt;, the signature is &lt;code&gt;sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17&lt;/code&gt; (&lt;a href="https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  What each provider signs
&lt;/h2&gt;

&lt;p&gt;Checked against each provider's official documentation on 2026-09-27.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Provider&lt;/th&gt;
&lt;th&gt;Header&lt;/th&gt;
&lt;th&gt;Signed content&lt;/th&gt;
&lt;th&gt;Algorithm and encoding&lt;/th&gt;
&lt;th&gt;Secret&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stripe&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Stripe-Signature&lt;/code&gt; (&lt;code&gt;t=…,v1=…&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;timestamp.body&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, hex&lt;/td&gt;
&lt;td&gt;Per-endpoint &lt;code&gt;whsec_…&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shopify&lt;/td&gt;
&lt;td&gt;&lt;code&gt;X-Shopify-Hmac-Sha256&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;body&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, base64&lt;/td&gt;
&lt;td&gt;The app's client secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-Hub-Signature-256&lt;/code&gt; (&lt;code&gt;sha256=…&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;body&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, hex&lt;/td&gt;
&lt;td&gt;The webhook's secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Slack&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;X-Slack-Signature&lt;/code&gt; (&lt;code&gt;v0=…&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v0:timestamp:body&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, hex&lt;/td&gt;
&lt;td&gt;The app's signing secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LINE&lt;/td&gt;
&lt;td&gt;&lt;code&gt;x-line-signature&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;body&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, base64&lt;/td&gt;
&lt;td&gt;Channel secret&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Twilio&lt;/td&gt;
&lt;td&gt;&lt;code&gt;X-Twilio-Signature&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;URL plus sorted POST params&lt;/td&gt;
&lt;td&gt;HMAC-SHA1, base64&lt;/td&gt;
&lt;td&gt;Auth token&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Standard Webhooks&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;webhook-signature&lt;/code&gt; (&lt;code&gt;v1,…&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;id.timestamp.body&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HMAC-SHA256, base64&lt;/td&gt;
&lt;td&gt;Base64-decoded part after &lt;code&gt;whsec_&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Sources: &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt;, &lt;a href="https://shopify.dev/docs/apps/build/webhooks/subscribe/https" rel="noopener noreferrer"&gt;Shopify&lt;/a&gt;, &lt;a href="https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;, &lt;a href="https://docs.slack.dev/authentication/verifying-requests-from-slack/" rel="noopener noreferrer"&gt;Slack&lt;/a&gt;, &lt;a href="https://developers.line.biz/en/reference/messaging-api/" rel="noopener noreferrer"&gt;LINE&lt;/a&gt;, &lt;a href="https://www.twilio.com/docs/usage/webhooks/webhooks-security" rel="noopener noreferrer"&gt;Twilio&lt;/a&gt;, &lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;Standard Webhooks spec&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Three things in that table trip people up:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Stripe and Standard Webhooks secrets both start with &lt;code&gt;whsec_&lt;/code&gt; but are used differently.&lt;/strong&gt; Stripe's libraries take the string as is. Standard Webhooks strips the prefix and base64-decodes the rest to get the key bytes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Shopify uses the app's client secret&lt;/strong&gt;, not a per-webhook secret.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Twilio signs the URL and parameters, not the body.&lt;/strong&gt; For JSON requests it adds a &lt;code&gt;bodySHA256&lt;/code&gt; query parameter with the hash of the raw body, and that becomes part of the signed URL. Twilio's docs tell you to use the exact URL configured in Twilio, including any URL-encoded characters.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Receive the body unparsed
&lt;/h2&gt;

&lt;p&gt;Fix cause number one in the framework: read the webhook route's body as bytes or a string before any JSON parser runs. In Express that means &lt;code&gt;express.raw({ type: 'application/json' })&lt;/code&gt; on the webhook route, registered before &lt;code&gt;app.use(express.json())&lt;/code&gt;; in the Next.js App Router, &lt;code&gt;await request.text()&lt;/code&gt;. The &lt;a href="https://webhookadmin.com/blog/webhook-raw-body-by-framework/" rel="noopener noreferrer"&gt;raw body guide&lt;/a&gt; has working code for eight frameworks.&lt;/p&gt;

&lt;p&gt;If you work with the body as a string, keep it UTF-8. GitHub's docs explicitly say to handle the payload as UTF-8, because payloads can contain Unicode characters. Decoding as Latin-1 and re-encoding changes any non-ASCII byte.&lt;/p&gt;

&lt;h2&gt;
  
  
  Compare in constant time
&lt;/h2&gt;

&lt;p&gt;Never compare signatures with &lt;code&gt;===&lt;/code&gt;. A normal string comparison stops at the first differing character, which leaks timing information. Use &lt;code&gt;crypto.timingSafeEqual&lt;/code&gt; in Node, &lt;code&gt;hmac.compare_digest&lt;/code&gt; in Python, or &lt;code&gt;crypto.subtle.verify&lt;/code&gt; with Web Crypto.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;timingSafeEqual&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:crypto&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;verifyGithub&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;header&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;expected&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256=&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nf"&gt;createHmac&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sha256&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;GITHUB_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;digest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;hex&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;got&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;header&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="c1"&gt;// timingSafeEqual throws on different lengths, so check first&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;got&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="nx"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nf"&gt;timingSafeEqual&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;got&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Timestamp tolerance and rotation
&lt;/h2&gt;

&lt;p&gt;Stripe's libraries and Slack both use a five-minute tolerance. If "timestamp too old" errors come and go, fix the server's clock (NTP) instead of widening the window; the window exists to stop replayed requests. &lt;a href="https://webhookadmin.com/blog/webhook-replay-attacks/" rel="noopener noreferrer"&gt;Webhook replay attacks&lt;/a&gt; covers how to choose it.&lt;/p&gt;

&lt;p&gt;If failures start right after a rotation, check how the provider signs during the overlap. Stripe can keep the old secret active for up to 24 hours and sends one signature per active secret. Standard Webhooks puts several space-separated signatures in &lt;code&gt;webhook-signature&lt;/code&gt;; any one matching is enough. A receiver that only reads the first signature breaks during that window. See &lt;a href="https://webhookadmin.com/blog/webhook-secret-rotation/" rel="noopener noreferrer"&gt;rotating signing secrets&lt;/a&gt; for the receiver-side steps.&lt;/p&gt;

&lt;h2&gt;
  
  
  Verifying webhooks from Webhook Admin
&lt;/h2&gt;

&lt;p&gt;Webhook Admin signs every message the Standard Webhooks way: &lt;code&gt;webhook-id&lt;/code&gt;, &lt;code&gt;webhook-timestamp&lt;/code&gt; and &lt;code&gt;webhook-signature&lt;/code&gt; headers, with an HMAC-SHA256 over &lt;code&gt;id.timestamp.body&lt;/code&gt;, base64-encoded after &lt;code&gt;v1,&lt;/code&gt;. On the receiving side, pass the raw body and headers to &lt;code&gt;Webhook.verify&lt;/code&gt; from the &lt;code&gt;webhookadmin&lt;/code&gt; npm package:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;express&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Webhook&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;webhookadmin&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;wh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// the endpoint's whsec_…&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/webhooks&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}),&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;wh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// { type, timestamp, data }&lt;/span&gt;
    &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you pass a parsed object, &lt;code&gt;verify&lt;/code&gt; throws an error that says it needs the raw request body. The default tolerance is five minutes either way, and during a rotation (24 hours) a signature from either secret verifies. The signing scheme is documented in &lt;a href="https://webhookadmin.com/docs/sdk/#scheme" rel="noopener noreferrer"&gt;signature verification&lt;/a&gt;, and the libraries for other languages are listed under &lt;a href="https://webhookadmin.com/docs/sdk/#libraries" rel="noopener noreferrer"&gt;libraries&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you send webhooks yourself and want signing, retries and delivery logs without building them, Webhook Admin is free up to 50,000 messages a month: &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Why does verification pass locally but fail in production?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Usually one of two things. You are using a different secret in production (a test secret, or the one the Stripe CLI printed), or something that only exists in production, such as a proxy or load balancer, is changing the body or the URL. Log the raw body and headers in production and replay the calculation locally to see which.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Does reordering JSON keys or changing whitespace change the signature?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes. The signature is computed over bytes. Two JSON documents that mean the same thing but differ in whitespace, key order, or number and Unicode formatting produce different signatures, so a body you parsed and stringified again will not verify.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Should I compare the signature as hex or base64?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;It depends on the provider. Stripe, GitHub and Slack use hex; Shopify, LINE, Twilio and Standard Webhooks use base64. Encode your computed HMAC the same way, then compare in constant time.&lt;/p&gt;




&lt;p&gt;Thanks for reading! What was the cause the last time a signature check failed for you? Tell us in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/blog/webhook-signature-verification-failed/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>security</category>
      <category>webdev</category>
      <category>api</category>
    </item>
    <item>
      <title>Centralizing Webhooks Across Products: Why and How</title>
      <dc:creator>mmiura</dc:creator>
      <pubDate>Wed, 07 Oct 2026 13:17:50 +0000</pubDate>
      <link>https://dev.to/shannonllc/centralizing-webhooks-across-products-why-and-how-3f8j</link>
      <guid>https://dev.to/shannonllc/centralizing-webhooks-across-products-why-and-how-3f8j</guid>
      <description>&lt;p&gt;&lt;em&gt;Billing signs with one header, accounts sends a static token, bookings never retries.&lt;/em&gt; If several of your products send webhooks, this is probably familiar. Here's why consolidating them into one delivery system pays off, when it doesn't, and how to migrate.&lt;/p&gt;

&lt;p&gt;If several of your products send webhooks, running delivery through one shared system costs less to build, less to operate and less for your receivers. You build signing, retries, delivery logs, failure alerts and SSRF protection once and every product uses them, and your customers get the same format no matter which product sent the event.&lt;/p&gt;

&lt;p&gt;This post covers what happens when each product builds its own, the reasons to centralize and public examples, when centralizing isn't worth it, the weak points of a shared system and how to handle them, choosing between an in-house platform and a service, and the migration steps. All sources were checked on 2026-09-30.&lt;/p&gt;

&lt;h2&gt;
  
  
  What happens when each product builds its own
&lt;/h2&gt;

&lt;p&gt;In short, you end up with the same components built slightly differently once per product, and both receivers and on-call engineers have to learn every variation.&lt;/p&gt;

&lt;p&gt;A typical picture: billing signs with HMAC in an &lt;code&gt;X-Signature&lt;/code&gt; header and retries three times, accounts sends a static token and no signature, bookings doesn't retry at all. Each works on its own, but the differences add up.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Area&lt;/th&gt;
&lt;th&gt;Built per product&lt;/th&gt;
&lt;th&gt;Centralized&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Signing&lt;/td&gt;
&lt;td&gt;Header name, signed string and encoding differ per product&lt;/td&gt;
&lt;td&gt;One format (for example Standard Webhooks)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retries&lt;/td&gt;
&lt;td&gt;Counts, intervals and success criteria vary&lt;/td&gt;
&lt;td&gt;One schedule and one definition of success&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Deduplication&lt;/td&gt;
&lt;td&gt;IDs missing or named differently&lt;/td&gt;
&lt;td&gt;Every event has an ID that doesn't change across retries&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Delivery logs&lt;/td&gt;
&lt;td&gt;Search each product's logs separately&lt;/td&gt;
&lt;td&gt;Search every product in one place&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Failure alerts&lt;/td&gt;
&lt;td&gt;Some products alert, to different places&lt;/td&gt;
&lt;td&gt;Same conditions, known destinations&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSRF protection&lt;/td&gt;
&lt;td&gt;Each implementation can miss a case&lt;/td&gt;
&lt;td&gt;Checked in one place&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Secret rotation&lt;/td&gt;
&lt;td&gt;Different procedure per product&lt;/td&gt;
&lt;td&gt;One procedure and one overlap period&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Receiver docs&lt;/td&gt;
&lt;td&gt;One document per product&lt;/td&gt;
&lt;td&gt;One document&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Why centralize
&lt;/h2&gt;

&lt;p&gt;There are six reasons, and they all come from building the same thing once and looking at it in one place.&lt;/p&gt;

&lt;h3&gt;
  
  
  One signature format
&lt;/h3&gt;

&lt;p&gt;Signature formats differ from sender to sender today. Svix, which started Standard Webhooks, described the problem in its announcement: "the ecosystem is fragmented, with each webhook provider using different implementations and varying quality." Consumers relearn verification for every provider, and providers redo already-solved problems such as security and forward compatibility (&lt;a href="https://www.svix.com/blog/standard-webhooks/" rel="noopener noreferrer"&gt;Announcing Standard Webhooks&lt;/a&gt;, 2023-12-13).&lt;/p&gt;

&lt;p&gt;The same thing happens inside one company. If each product signs differently, the same customer writes verification code more than once. Route delivery through one system and there is only one format. The Standard Webhooks technical steering committee includes people from Zapier, Twilio, Lob, Mux, ngrok, Supabase, Svix and Kong (&lt;a href="https://www.standardwebhooks.com/" rel="noopener noreferrer"&gt;Standard Webhooks&lt;/a&gt;), which makes it a reasonable default. The spec itself is covered in &lt;a href="https://webhookadmin.com/blog/standard-webhooks-explained/" rel="noopener noreferrer"&gt;Standard Webhooks explained&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Consistent retries and deduplication
&lt;/h3&gt;

&lt;p&gt;Receivers need an event ID that stays the same across retries to drop duplicates. The Standard Webhooks spec defines &lt;code&gt;webhook-id&lt;/code&gt; as an identifier that "remains the same no matter how many times a webhook that has failed is retried," and recommends a retry schedule spanning multiple days with exponential backoff and some random jitter (&lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;spec&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;When each product builds its own, some send no ID and some generate a new one per attempt. One system gives every event an ID under the same rule and retries on the same schedule. See &lt;a href="https://webhookadmin.com/blog/webhook-retry-design/" rel="noopener noreferrer"&gt;webhook retry design&lt;/a&gt; for choosing intervals and &lt;a href="https://webhookadmin.com/blog/webhook-idempotency-duplicates/" rel="noopener noreferrer"&gt;handling duplicate webhooks&lt;/a&gt; for the receiver side.&lt;/p&gt;

&lt;h3&gt;
  
  
  One place for logs and monitoring
&lt;/h3&gt;

&lt;p&gt;When a customer says "we didn't get the webhook," the first thing you check is the delivery log. If logs live in a different place per product, you start by working out which product sent it. With one system you search across every product by event ID or customer ID.&lt;/p&gt;

&lt;p&gt;Alerts work the same way. You watch the same metrics, how long each endpoint has been failing and the total retry backlog, under the same conditions for every product, and on-call learns one dashboard and one runbook. The metrics are covered in &lt;a href="https://webhookadmin.com/blog/webhook-monitoring-alerts/" rel="noopener noreferrer"&gt;monitoring outgoing webhooks&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Security built once
&lt;/h3&gt;

&lt;p&gt;A webhook sender makes requests from its own servers to whatever URL a customer registers. Register an internal address or a cloud metadata address and you have an SSRF hole. The Standard Webhooks spec recommends sending through a proxy that filters internal IP addresses and putting webhook workers in a private subnet that can't reach internal services (&lt;a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md" rel="noopener noreferrer"&gt;spec&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;That protection has to run both at registration and right before each send, and a single gap defeats it. Implement it per product and you have that many places to audit. Encrypted secret storage, secret rotation and static source IPs are the same: build them once and every product gets them. See &lt;a href="https://webhookadmin.com/blog/webhook-ssrf-protection/" rel="noopener noreferrer"&gt;SSRF protection for webhook senders&lt;/a&gt; and &lt;a href="https://webhookadmin.com/blog/webhook-secret-rotation/" rel="noopener noreferrer"&gt;rotating signing secrets&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  One webhook experience for customers
&lt;/h3&gt;

&lt;p&gt;Customers don't think of these as "the billing webhooks" and "the bookings webhooks"; they're your company's webhooks. One signature format, one retry policy, one set of source IPs, one set of docs and one page for managing endpoints means less integration work and fewer support tickets. See &lt;a href="https://webhookadmin.com/blog/webhook-docs-for-consumers/" rel="noopener noreferrer"&gt;what to put in your webhook documentation&lt;/a&gt; and &lt;a href="https://webhookadmin.com/blog/webhook-customer-portal/" rel="noopener noreferrer"&gt;customer-facing webhook portals&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  No duplicate implementations
&lt;/h3&gt;

&lt;p&gt;The expensive part of sending webhooks isn't the POST. It's retries, logging, auto-disabling, alerting, secret rotation and the customer portal (the full list is in &lt;a href="https://webhookadmin.com/blog/build-vs-buy-webhooks/" rel="noopener noreferrer"&gt;build vs buy&lt;/a&gt;). Build those once per product and you multiply both the build and the maintenance.&lt;/p&gt;

&lt;p&gt;The CNCF Platforms White Paper gives two reasons for shared platforms: to "reduce the cognitive load on product teams and thereby accelerate product development and delivery," and to accelerate delivery "by reusing and sharing platform tools and knowledge across many teams in an enterprise" (&lt;a href="https://tag-app-delivery.cncf.io/whitepapers/platforms/" rel="noopener noreferrer"&gt;CNCF Platforms White Paper&lt;/a&gt;, "Why platforms?"). Webhook delivery fits that description closely.&lt;/p&gt;

&lt;h2&gt;
  
  
  Public examples
&lt;/h2&gt;

&lt;p&gt;Large webhook senders deliver events from different products and event types through one system, in one format. Their internal architecture isn't public, but the consistency receivers see is documented.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Company&lt;/th&gt;
&lt;th&gt;What's consistent&lt;/th&gt;
&lt;th&gt;Source&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stripe&lt;/td&gt;
&lt;td&gt;Events from payments, billing, Connect and more arrive at the same kind of webhook endpoint, signed with &lt;code&gt;Stripe-Signature&lt;/code&gt;, retried in live mode for up to 3 days with exponential backoff, with deliveries shown in one place in Workbench. An organization spanning several accounts can have a single event destination&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub&lt;/td&gt;
&lt;td&gt;Repository, organization, GitHub App, Marketplace and Sponsors webhooks carry the same headers (&lt;code&gt;X-GitHub-Delivery&lt;/code&gt;, &lt;code&gt;X-Hub-Signature-256&lt;/code&gt; and others), and the User-Agent always starts with &lt;code&gt;GitHub-Hookshot/&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads" rel="noopener noreferrer"&gt;Webhook events and payloads&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Twilio&lt;/td&gt;
&lt;td&gt;Event Streams consolidates "events from all supported Twilio products including Messaging, TaskRouter, Voice, and more into a single data feed," delivered to webhooks, Amazon Kinesis or Segment&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.twilio.com/docs/events" rel="noopener noreferrer"&gt;Event Streams&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shopify&lt;/td&gt;
&lt;td&gt;Every topic carries &lt;code&gt;X-Shopify-Topic&lt;/code&gt;, &lt;code&gt;X-Shopify-Webhook-Id&lt;/code&gt; and &lt;code&gt;X-Shopify-Hmac-Sha256&lt;/code&gt;, and subscriptions can target a URL, Google Pub/Sub or Amazon EventBridge&lt;/td&gt;
&lt;td&gt;&lt;a href="https://shopify.dev/docs/apps/build/webhooks" rel="noopener noreferrer"&gt;Shopify webhooks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;From the receiver's side, these companies can add products without receivers writing new verification or deduplication code. That's the same outcome a multi-product company is after.&lt;/p&gt;

&lt;h2&gt;
  
  
  When centralizing isn't worth it
&lt;/h2&gt;

&lt;p&gt;You don't need to centralize if any of these apply:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Only one product sends webhooks and that isn't going to change&lt;/li&gt;
&lt;li&gt;You deliver to one or two internal endpoints, not to customers&lt;/li&gt;
&lt;li&gt;You have a few event types and customers don't need to see delivery logs&lt;/li&gt;
&lt;li&gt;The sending product is about to be sold or spun off, and a shared system would make the separation harder&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In the first two cases, putting sends on your existing job queue is enough. Sign in the Standard Webhooks format from the start anyway, so a later move to a shared system doesn't require receivers to change anything.&lt;/p&gt;

&lt;h2&gt;
  
  
  Weak points of a shared system, and how to handle them
&lt;/h2&gt;

&lt;p&gt;The risk is that one outage, or one customer's slow endpoint, affects every product. Design it out like this:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Risk&lt;/th&gt;
&lt;th&gt;Mitigation&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;If the shared system stops, every product stops sending&lt;/td&gt;
&lt;td&gt;Persist before acknowledging and deliver asynchronously through a queue. In each product, write to an outbox when the send call fails and retry later&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One slow endpoint slows everything down&lt;/td&gt;
&lt;td&gt;Per-endpoint concurrency limits, short timeouts, and pausing endpoints that keep failing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One product's burst of events clogs the rest&lt;/td&gt;
&lt;td&gt;API rate limits and monthly quotas per product (project)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access becomes too broad&lt;/td&gt;
&lt;td&gt;Separate API keys and member access per product, and keep an audit log&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Migration effort&lt;/td&gt;
&lt;td&gt;Move one product at a time, and send both old and new signatures during the move&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The outbox approach is in &lt;a href="https://webhookadmin.com/blog/webhook-outbox-pattern/" rel="noopener noreferrer"&gt;the transactional outbox pattern&lt;/a&gt;, and per-endpoint isolation in &lt;a href="https://webhookadmin.com/blog/multi-tenant-webhooks/" rel="noopener noreferrer"&gt;multi-tenant webhook delivery&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  In-house platform or delivery service
&lt;/h2&gt;

&lt;p&gt;Either one gives you a single system. The difference is how much you build and who operates it.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;In-house platform&lt;/th&gt;
&lt;th&gt;Delivery service&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Fits when&lt;/td&gt;
&lt;td&gt;You have a platform team that can own webhook delivery long term&lt;/td&gt;
&lt;td&gt;You don't have a platform team, or don't want dedicated staff on webhook delivery&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Up-front build&lt;/td&gt;
&lt;td&gt;Sending API, queue, retries, logs, alerts, SSRF protection, customer portal&lt;/td&gt;
&lt;td&gt;The call from each product to the sending API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ongoing work&lt;/td&gt;
&lt;td&gt;Incidents, capacity, log retention&lt;/td&gt;
&lt;td&gt;Usage-based fees and responding to alerts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Where data lives&lt;/td&gt;
&lt;td&gt;Your environment&lt;/td&gt;
&lt;td&gt;The provider's (some offer self-hosting)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Delivery services include Svix, Hookdeck Outpost, Convoy and Webhook Admin. Pricing, retention and static IPs are compared in &lt;a href="https://webhookadmin.com/blog/webhook-delivery-services-compared/" rel="noopener noreferrer"&gt;webhook delivery services compared&lt;/a&gt;, and building versus buying in &lt;a href="https://webhookadmin.com/blog/build-vs-buy-webhooks/" rel="noopener noreferrer"&gt;build vs buy&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to centralize
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Inventory what you send today&lt;/strong&gt;: which products send webhooks, their event types, signature formats, retry behavior, number of endpoints and receiver docs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Write down shared rules&lt;/strong&gt;: signature format (we recommend Standard Webhooks), event type naming, retry schedule, timeout, what counts as success, and when to auto-disable an endpoint.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pick the system&lt;/strong&gt;: build a platform or use a service, using the table above. Make per-product separation of logs and access a requirement.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Decide where alerts go&lt;/strong&gt;: to each product's owners and to whoever watches the whole system.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Move one product at a time&lt;/strong&gt;: start with new event types or the product with the fewest endpoints. Send both old and new signatures during the move, and drop the old one once receivers have switched.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Merge receiver docs and settings pages&lt;/strong&gt;: one place for signature verification, retry policy, source IPs and endpoint registration.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;See &lt;a href="https://webhookadmin.com/blog/webhook-event-types-design/" rel="noopener noreferrer"&gt;designing webhook event types&lt;/a&gt; for naming and &lt;a href="https://webhookadmin.com/blog/migrate-webhook-provider/" rel="noopener noreferrer"&gt;migrating webhook providers&lt;/a&gt; for the migration steps.&lt;/p&gt;

&lt;h2&gt;
  
  
  Centralizing with Webhook Admin
&lt;/h2&gt;

&lt;p&gt;In Webhook Admin, your company is an organization, each product is a project, and each project has a production and a test environment. API keys are issued per environment, so sending access is separated per product.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A view across all projects&lt;/strong&gt;: the organization overview shows sends, success rate and endpoints needing attention over the last 24 hours for every project, and you can search production delivery logs across all projects.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The same signing and retries everywhere&lt;/strong&gt;: every project signs in the Standard Webhooks format and by default makes up to 8 attempts, including the first, over about 28 hours. Endpoints failing for 5 days are disabled automatically.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Failure alerts&lt;/strong&gt;: to Slack, Teams, Chatwork, email or a webhook, per project or for the whole organization in one place.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;SSRF protection&lt;/strong&gt;: endpoint URLs are checked at registration, and DNS results are checked again right before each send.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Customer portal&lt;/strong&gt;: from Starter, your customers can manage their own endpoints, event types, secrets, logs and retries in a portal you embed in your app.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Audit log, API and MCP&lt;/strong&gt;: organization actions are recorded, and you can register endpoints and retry failed deliveries through the public API and MCP.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Projects are limited to 1 on Free, 3 on Starter, 10 on Pro and unlimited on Business. Free includes 50,000 messages a month: &lt;a href="https://app.webhookadmin.com/signup" rel="noopener noreferrer"&gt;https://app.webhookadmin.com/signup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Is it worth centralizing with only two products?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes, if the same customers receive webhooks from both. They get one signature format and one retry policy, and write verification code once. If each product has different receivers and you don't expect more products, keeping them separate is fine.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Doesn't one shared system mean one outage stops every product's webhooks?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Not if you design for it. Persist a message before acknowledging it and deliver asynchronously through a queue. Limit concurrent deliveries per endpoint, pause failing endpoints, and rate-limit the API per product (project). If you use a service, check its published SLA and incident history.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Our products already sign webhooks in different formats. Can we move without breaking receivers?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Yes. Send both the old and the new signature for a while, confirm receivers have switched to verifying the new one, then drop the old one. The steps are in our post on migrating webhook providers.&lt;/p&gt;




&lt;p&gt;Thanks for reading! Does your company run one webhook system for every product, or does each team own its own? Tell us how it's working in the comments.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This post first appeared on the &lt;a href="https://webhookadmin.com/blog/centralize-webhooks/" rel="noopener noreferrer"&gt;Webhook Admin blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webhooks</category>
      <category>api</category>
      <category>architecture</category>
      <category>saas</category>
    </item>
  </channel>
</rss>
