[{"data":1,"prerenderedAt":762},["ShallowReactive",2],{"content-query-3rOP0SmU1D":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"layout":10,"crumb":11,"term":11,"summary":12,"group":13,"order":14,"updated":15,"cta":16,"related":24,"faq":43,"body":56,"_type":755,"_id":756,"_source":757,"_file":758,"_stem":759,"_extension":760,"sitemap":761},"/glossary/webhook-payload","glossary",false,"","What is a webhook payload? Structure and examples","A webhook payload is the data in the body of a webhook request, usually JSON describing the event. Example payloads, formats, size limits and how to handle them safely.","reference","Webhook payload","The event data in the body of a webhook request.","Basics",4,"2026-10-28",{"eyebrow":17,"title":18,"text":19,"to":20,"label":21,"secondaryTo":22,"secondaryLabel":23},"Webhook Bin","See the exact payload a provider sends","Point any provider at a free Webhook Bin URL and inspect every request: method, headers, query and the raw body. No signup. When the payload isn't the shape your destination expects, Webhook Relay functions can transform it in flight.","/webhook-bin/","Inspect a payload","/features/transform-webhooks/","Transform payloads",[25,28,31,34,37,40],{"title":26,"to":27},"Webhook endpoint","/glossary/webhook-endpoint/",{"title":29,"to":30},"Webhook signature","/glossary/webhook-signature/",{"title":32,"to":33},"Idempotency","/glossary/idempotency/",{"title":35,"to":36},"413 Payload Too Large","/http-errors/413-payload-too-large/",{"title":38,"to":39},"400 vs 422","/http-errors/400-vs-422/",{"title":41,"to":42},"Large webhooks","/docs/webhooks/large-webhooks/",[44,47,50,53],{"q":45,"a":46},"What is a webhook payload?","A webhook payload is the data in the body of a webhook HTTP request. It describes the event that happened, usually as a JSON object with an event ID, an event type, a timestamp and the affected resource, such as the payment or the pull request.",{"q":48,"a":49},"What format are webhook payloads in?","Most modern providers send JSON with a Content-Type of application/json. Some send form-encoded bodies, for example Twilio and Slack slash commands, and a few older or enterprise systems send XML. Always check the Content-Type header rather than assuming JSON.",{"q":51,"a":52},"What is the difference between a thin and a fat webhook payload?","A fat payload contains the full resource, so the receiver can act without calling back. A thin payload contains only the event type and an ID, and the receiver fetches the current state from the provider's API. Thin payloads are always fresh and smaller, but cost an extra API call.",{"q":54,"a":55},"How large can a webhook payload be?","It depends on the provider and the receiver. GitHub caps payloads at 25 MB, and many receivers and proxies reject bodies of a few megabytes with 413 Payload Too Large. Webhook Relay accepts webhooks up to 4 MB by default and up to 40 MB when large webhooks are enabled.",{"type":57,"children":58,"toc":747},"root",[59,88,254,261,421,456,462,529,542,548,567,573,687,693,723,729,741],{"type":60,"tag":61,"props":62,"children":63},"element","p",{},[64,71,73,79,81,86],{"type":60,"tag":65,"props":66,"children":67},"strong",{},[68],{"type":69,"value":70},"text","A webhook payload is the data in the body of a webhook HTTP request: a description of the event that just happened, usually as JSON.",{"type":69,"value":72}," It typically includes an event ID, an event type, a timestamp and the resource the event is about. The provider sends it to your ",{"type":60,"tag":74,"props":75,"children":76},"a",{"href":27},[77],{"type":69,"value":78},"webhook endpoint",{"type":69,"value":80},", along with headers that identify and ",{"type":60,"tag":74,"props":82,"children":83},{"href":30},[84],{"type":69,"value":85},"sign",{"type":69,"value":87}," it.",{"type":60,"tag":89,"props":90,"children":94},"pre",{"className":91,"code":92,"language":93,"meta":7,"style":7},"language-http shiki shiki-themes github-dark","POST /webhooks/billing HTTP/1.1\nContent-Type: application/json\nwebhook-id: msg_2xKq8f3Ld9\nwebhook-timestamp: 1793180400\nwebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n\n{\n  \"id\": \"evt_01JBX8Q3\",\n  \"type\": \"invoice.paid\",\n  \"created_at\": \"2026-10-28T09:00:00Z\",\n  \"data\": {\n    \"invoice_id\": \"inv_8842\",\n    \"customer_id\": \"cus_193\",\n    \"amount\": 4900,\n    \"currency\": \"usd\"\n  }\n}\n","http",[95],{"type":60,"tag":96,"props":97,"children":98},"code",{"__ignoreMap":7},[99,110,119,128,136,145,155,164,173,182,191,200,209,218,227,236,245],{"type":60,"tag":100,"props":101,"children":104},"span",{"class":102,"line":103},"line",1,[105],{"type":60,"tag":100,"props":106,"children":107},{},[108],{"type":69,"value":109},"POST /webhooks/billing HTTP/1.1\n",{"type":60,"tag":100,"props":111,"children":113},{"class":102,"line":112},2,[114],{"type":60,"tag":100,"props":115,"children":116},{},[117],{"type":69,"value":118},"Content-Type: application/json\n",{"type":60,"tag":100,"props":120,"children":122},{"class":102,"line":121},3,[123],{"type":60,"tag":100,"props":124,"children":125},{},[126],{"type":69,"value":127},"webhook-id: msg_2xKq8f3Ld9\n",{"type":60,"tag":100,"props":129,"children":130},{"class":102,"line":14},[131],{"type":60,"tag":100,"props":132,"children":133},{},[134],{"type":69,"value":135},"webhook-timestamp: 1793180400\n",{"type":60,"tag":100,"props":137,"children":139},{"class":102,"line":138},5,[140],{"type":60,"tag":100,"props":141,"children":142},{},[143],{"type":69,"value":144},"webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n",{"type":60,"tag":100,"props":146,"children":148},{"class":102,"line":147},6,[149],{"type":60,"tag":100,"props":150,"children":152},{"emptyLinePlaceholder":151},true,[153],{"type":69,"value":154},"\n",{"type":60,"tag":100,"props":156,"children":158},{"class":102,"line":157},7,[159],{"type":60,"tag":100,"props":160,"children":161},{},[162],{"type":69,"value":163},"{\n",{"type":60,"tag":100,"props":165,"children":167},{"class":102,"line":166},8,[168],{"type":60,"tag":100,"props":169,"children":170},{},[171],{"type":69,"value":172},"  \"id\": \"evt_01JBX8Q3\",\n",{"type":60,"tag":100,"props":174,"children":176},{"class":102,"line":175},9,[177],{"type":60,"tag":100,"props":178,"children":179},{},[180],{"type":69,"value":181},"  \"type\": \"invoice.paid\",\n",{"type":60,"tag":100,"props":183,"children":185},{"class":102,"line":184},10,[186],{"type":60,"tag":100,"props":187,"children":188},{},[189],{"type":69,"value":190},"  \"created_at\": \"2026-10-28T09:00:00Z\",\n",{"type":60,"tag":100,"props":192,"children":194},{"class":102,"line":193},11,[195],{"type":60,"tag":100,"props":196,"children":197},{},[198],{"type":69,"value":199},"  \"data\": {\n",{"type":60,"tag":100,"props":201,"children":203},{"class":102,"line":202},12,[204],{"type":60,"tag":100,"props":205,"children":206},{},[207],{"type":69,"value":208},"    \"invoice_id\": \"inv_8842\",\n",{"type":60,"tag":100,"props":210,"children":212},{"class":102,"line":211},13,[213],{"type":60,"tag":100,"props":214,"children":215},{},[216],{"type":69,"value":217},"    \"customer_id\": \"cus_193\",\n",{"type":60,"tag":100,"props":219,"children":221},{"class":102,"line":220},14,[222],{"type":60,"tag":100,"props":223,"children":224},{},[225],{"type":69,"value":226},"    \"amount\": 4900,\n",{"type":60,"tag":100,"props":228,"children":230},{"class":102,"line":229},15,[231],{"type":60,"tag":100,"props":232,"children":233},{},[234],{"type":69,"value":235},"    \"currency\": \"usd\"\n",{"type":60,"tag":100,"props":237,"children":239},{"class":102,"line":238},16,[240],{"type":60,"tag":100,"props":241,"children":242},{},[243],{"type":69,"value":244},"  }\n",{"type":60,"tag":100,"props":246,"children":248},{"class":102,"line":247},17,[249],{"type":60,"tag":100,"props":250,"children":251},{},[252],{"type":69,"value":253},"}\n",{"type":60,"tag":255,"props":256,"children":258},"h2",{"id":257},"whats-in-a-typical-payload",[259],{"type":69,"value":260},"What's in a typical payload",{"type":60,"tag":262,"props":263,"children":264},"table",{},[265,284],{"type":60,"tag":266,"props":267,"children":268},"thead",{},[269],{"type":60,"tag":270,"props":271,"children":272},"tr",{},[273,279],{"type":60,"tag":274,"props":275,"children":276},"th",{},[277],{"type":69,"value":278},"Field",{"type":60,"tag":274,"props":280,"children":281},{},[282],{"type":69,"value":283},"Purpose",{"type":60,"tag":285,"props":286,"children":287},"tbody",{},[288,317,368,381,408],{"type":60,"tag":270,"props":289,"children":290},{},[291,305],{"type":60,"tag":292,"props":293,"children":294},"td",{},[295,297,303],{"type":69,"value":296},"Event ID (",{"type":60,"tag":96,"props":298,"children":300},{"className":299},[],[301],{"type":69,"value":302},"id",{"type":69,"value":304},")",{"type":60,"tag":292,"props":306,"children":307},{},[308,310,315],{"type":69,"value":309},"Unique per event. Use it to deduplicate retries. See ",{"type":60,"tag":74,"props":311,"children":312},{"href":33},[313],{"type":69,"value":314},"idempotency",{"type":69,"value":316},".",{"type":60,"tag":270,"props":318,"children":319},{},[320,347],{"type":60,"tag":292,"props":321,"children":322},{},[323,325,331,333,339,340,346],{"type":69,"value":324},"Event type (",{"type":60,"tag":96,"props":326,"children":328},{"className":327},[],[329],{"type":69,"value":330},"type",{"type":69,"value":332},", ",{"type":60,"tag":96,"props":334,"children":336},{"className":335},[],[337],{"type":69,"value":338},"event",{"type":69,"value":332},{"type":60,"tag":96,"props":341,"children":343},{"className":342},[],[344],{"type":69,"value":345},"action",{"type":69,"value":304},{"type":60,"tag":292,"props":348,"children":349},{},[350,352,358,360,366],{"type":69,"value":351},"Lets one endpoint route ",{"type":60,"tag":96,"props":353,"children":355},{"className":354},[],[356],{"type":69,"value":357},"invoice.paid",{"type":69,"value":359}," and ",{"type":60,"tag":96,"props":361,"children":363},{"className":362},[],[364],{"type":69,"value":365},"invoice.failed",{"type":69,"value":367}," to different handlers.",{"type":60,"tag":270,"props":369,"children":370},{},[371,376],{"type":60,"tag":292,"props":372,"children":373},{},[374],{"type":69,"value":375},"Timestamp",{"type":60,"tag":292,"props":377,"children":378},{},[379],{"type":69,"value":380},"When the event happened. Useful for ordering, since deliveries can arrive out of order.",{"type":60,"tag":270,"props":382,"children":383},{},[384,403],{"type":60,"tag":292,"props":385,"children":386},{},[387,389,395,396,402],{"type":69,"value":388},"Resource (",{"type":60,"tag":96,"props":390,"children":392},{"className":391},[],[393],{"type":69,"value":394},"data",{"type":69,"value":332},{"type":60,"tag":96,"props":397,"children":399},{"className":398},[],[400],{"type":69,"value":401},"object",{"type":69,"value":304},{"type":60,"tag":292,"props":404,"children":405},{},[406],{"type":69,"value":407},"The thing that changed, either in full or as a reference.",{"type":60,"tag":270,"props":409,"children":410},{},[411,416],{"type":60,"tag":292,"props":412,"children":413},{},[414],{"type":69,"value":415},"API version",{"type":60,"tag":292,"props":417,"children":418},{},[419],{"type":69,"value":420},"Some providers (Stripe, for example) pin the payload shape to an API version.",{"type":60,"tag":61,"props":422,"children":423},{},[424,426,432,433,439,441,447,449,455],{"type":69,"value":425},"Some providers put the event type or delivery ID in headers instead. GitHub sends ",{"type":60,"tag":96,"props":427,"children":429},{"className":428},[],[430],{"type":69,"value":431},"X-GitHub-Event",{"type":69,"value":359},{"type":60,"tag":96,"props":434,"children":436},{"className":435},[],[437],{"type":69,"value":438},"X-GitHub-Delivery",{"type":69,"value":440},", and the ",{"type":60,"tag":74,"props":442,"children":444},{"href":443},"/glossary/standard-webhooks/",[445],{"type":69,"value":446},"Standard Webhooks",{"type":69,"value":448}," spec uses ",{"type":60,"tag":96,"props":450,"children":452},{"className":451},[],[453],{"type":69,"value":454},"webhook-id",{"type":69,"value":316},{"type":60,"tag":255,"props":457,"children":459},{"id":458},"payload-formats",[460],{"type":69,"value":461},"Payload formats",{"type":60,"tag":463,"props":464,"children":465},"ul",{},[466,485,509,519],{"type":60,"tag":467,"props":468,"children":469},"li",{},[470,475,477,483],{"type":60,"tag":65,"props":471,"children":472},{},[473],{"type":69,"value":474},"JSON",{"type":69,"value":476}," (",{"type":60,"tag":96,"props":478,"children":480},{"className":479},[],[481],{"type":69,"value":482},"application/json",{"type":69,"value":484},"): Stripe, GitHub, Shopify and most modern APIs.",{"type":60,"tag":467,"props":486,"children":487},{},[488,493,494,500,502,508],{"type":60,"tag":65,"props":489,"children":490},{},[491],{"type":69,"value":492},"Form-encoded",{"type":69,"value":476},{"type":60,"tag":96,"props":495,"children":497},{"className":496},[],[498],{"type":69,"value":499},"application/x-www-form-urlencoded",{"type":69,"value":501},"): Twilio, Slack slash commands, and some older systems. Slack's interactive payloads are a JSON string inside a form field called ",{"type":60,"tag":96,"props":503,"children":505},{"className":504},[],[506],{"type":69,"value":507},"payload",{"type":69,"value":316},{"type":60,"tag":467,"props":510,"children":511},{},[512,517],{"type":60,"tag":65,"props":513,"children":514},{},[515],{"type":69,"value":516},"XML",{"type":69,"value":518},": some payment, telecom and enterprise systems.",{"type":60,"tag":467,"props":520,"children":521},{},[522,527],{"type":60,"tag":65,"props":523,"children":524},{},[525],{"type":69,"value":526},"Multipart",{"type":69,"value":528},": inbound email services that send attachments.",{"type":60,"tag":61,"props":530,"children":531},{},[532,534,540],{"type":69,"value":533},"Read the ",{"type":60,"tag":96,"props":535,"children":537},{"className":536},[],[538],{"type":69,"value":539},"Content-Type",{"type":69,"value":541}," header and parse accordingly.",{"type":60,"tag":255,"props":543,"children":545},{"id":544},"fat-vs-thin-payloads",[546],{"type":69,"value":547},"Fat vs thin payloads",{"type":60,"tag":61,"props":549,"children":550},{},[551,553,558,560,565],{"type":69,"value":552},"A ",{"type":60,"tag":65,"props":554,"children":555},{},[556],{"type":69,"value":557},"fat",{"type":69,"value":559}," payload carries the full resource, so you can act on it directly. A ",{"type":60,"tag":65,"props":561,"children":562},{},[563],{"type":69,"value":564},"thin",{"type":69,"value":566}," payload carries only the type and an ID, and you call the provider's API for the current state. Thin payloads are smaller, never stale, and limit the damage if a payload leaks, at the cost of an extra API request per event. Even with fat payloads, fetching the latest state before acting is a safe pattern when events can arrive out of order.",{"type":60,"tag":255,"props":568,"children":570},{"id":569},"handling-payloads-safely",[571],{"type":69,"value":572},"Handling payloads safely",{"type":60,"tag":574,"props":575,"children":576},"ol",{},[577,595,620,652,670],{"type":60,"tag":467,"props":578,"children":579},{},[580,585,587,593],{"type":60,"tag":65,"props":581,"children":582},{},[583],{"type":69,"value":584},"Keep the raw bytes.",{"type":69,"value":586}," Signatures are computed over the exact body. If a framework parses and re-serializes JSON first, whitespace or key order changes and verification fails. In Express, use ",{"type":60,"tag":96,"props":588,"children":590},{"className":589},[],[591],{"type":69,"value":592},"express.raw()",{"type":69,"value":594}," on the webhook route.",{"type":60,"tag":467,"props":596,"children":597},{},[598,603,605,610,612,618],{"type":60,"tag":65,"props":599,"children":600},{},[601],{"type":69,"value":602},"Verify, then parse.",{"type":69,"value":604}," Check the ",{"type":60,"tag":74,"props":606,"children":607},{"href":30},[608],{"type":69,"value":609},"signature",{"type":69,"value":611}," with your ",{"type":60,"tag":74,"props":613,"children":615},{"href":614},"/glossary/webhook-secret/",[616],{"type":69,"value":617},"webhook secret",{"type":69,"value":619}," before trusting any field.",{"type":60,"tag":467,"props":621,"children":622},{},[623,628,630,636,638,644,646,650],{"type":60,"tag":65,"props":624,"children":625},{},[626],{"type":69,"value":627},"Validate the shape.",{"type":69,"value":629}," Return ",{"type":60,"tag":96,"props":631,"children":633},{"className":632},[],[634],{"type":69,"value":635},"400",{"type":69,"value":637}," for a body you can't parse and ",{"type":60,"tag":96,"props":639,"children":641},{"className":640},[],[642],{"type":69,"value":643},"422",{"type":69,"value":645}," for a valid body you can't accept. See ",{"type":60,"tag":74,"props":647,"children":648},{"href":39},[649],{"type":69,"value":38},{"type":69,"value":651},". Most providers retry both, so log them.",{"type":60,"tag":467,"props":653,"children":654},{},[655,660,662,668],{"type":60,"tag":65,"props":656,"children":657},{},[658],{"type":69,"value":659},"Ignore unknown fields and event types.",{"type":69,"value":661}," Providers add fields without warning. Acknowledge events you don't handle with ",{"type":60,"tag":96,"props":663,"children":665},{"className":664},[],[666],{"type":69,"value":667},"200",{"type":69,"value":669}," so they aren't retried.",{"type":60,"tag":467,"props":671,"children":672},{},[673,678,680,685],{"type":60,"tag":65,"props":674,"children":675},{},[676],{"type":69,"value":677},"Store before processing.",{"type":69,"value":679}," Write the raw payload to a queue or table, return ",{"type":60,"tag":96,"props":681,"children":683},{"className":682},[],[684],{"type":69,"value":667},{"type":69,"value":686},", and process asynchronously.",{"type":60,"tag":255,"props":688,"children":690},{"id":689},"size-limits",[691],{"type":69,"value":692},"Size limits",{"type":60,"tag":61,"props":694,"children":695},{},[696,698,704,706,714,716,721],{"type":69,"value":697},"Providers cap what they send (GitHub caps payloads at 25 MB), and receivers cap what they accept: nginx defaults ",{"type":60,"tag":96,"props":699,"children":701},{"className":700},[],[702],{"type":69,"value":703},"client_max_body_size",{"type":69,"value":705}," to 1 MB, and many serverless platforms limit request bodies to a few megabytes. Anything over the limit fails with ",{"type":60,"tag":74,"props":707,"children":708},{"href":36},[709],{"type":60,"tag":96,"props":710,"children":712},{"className":711},[],[713],{"type":69,"value":35},{"type":69,"value":715},". Webhook Relay accepts 4 MB per webhook by default and up to 40 MB with ",{"type":60,"tag":74,"props":717,"children":718},{"href":42},[719],{"type":69,"value":720},"large webhooks",{"type":69,"value":722}," enabled.",{"type":60,"tag":255,"props":724,"children":726},{"id":725},"when-the-payload-is-the-wrong-shape",[727],{"type":69,"value":728},"When the payload is the wrong shape",{"type":60,"tag":61,"props":730,"children":731},{},[732,734,739],{"type":69,"value":733},"If a destination expects a different structure, for example forwarding a Stripe event into a Slack message, you can reshape it in code, or ",{"type":60,"tag":74,"props":735,"children":736},{"href":22},[737],{"type":69,"value":738},"transform the webhook",{"type":69,"value":740}," in flight with a Webhook Relay function before it's delivered.",{"type":60,"tag":742,"props":743,"children":744},"style",{},[745],{"type":69,"value":746},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":7,"searchDepth":121,"depth":121,"links":748},[749,750,751,752,753,754],{"id":257,"depth":112,"text":260},{"id":458,"depth":112,"text":461},{"id":544,"depth":112,"text":547},{"id":569,"depth":112,"text":572},{"id":689,"depth":112,"text":692},{"id":725,"depth":112,"text":728},"markdown","content:glossary:webhook-payload.md","content","glossary/webhook-payload.md","glossary/webhook-payload","md",{"loc":4},1793199804802]