All chapters
  1. Start hereA valid token is not a permission
  2. Foundations · 1Identity and trust primitives: who is calling, and who checks
  3. Foundations · 2People and identity proofing: accounts, passwords and recovery
  4. Foundations · 3Sessions and browser security: cookies, CSRF, XSS and the BFF
  5. Foundations · 4Authenticators and MFA: passwords, passkeys and phishing resistance
  6. Foundations · 5API keys and application credentials: what a key proves
  7. Foundations · 6Tokens: bearer, JWT anatomy, validation and revocation
  8. Foundations · 7OAuth, OpenID Connect and federation: delegation and login
  9. Authorization · 8Authorization from first principles: subject, action, resource, context
  10. Authorization · 9Access control models: RBAC, ABAC, ReBAC and ownership
  11. Authorization · 10The enforcement architecture: PEP, PDP, PIP and PAP
  12. Authorization · 11Policy as code: versions, tests, engines and decision logs
  13. Authorization · 12Tenant and data isolation: one platform, many brokerages
  14. Authorization · 13Identity governance and lifecycle: joiner, mover, leaver
  15. Authorization · 14Privileged access: standing rights, just-in-time elevation and break-glass
  16. Workloads · 15TLS, PKI and certificates: proving a host, and a client
  17. Workloads · 16Workload and service identity: SPIFFE, mTLS and caller allowlists
  18. Workloads · 17API gateways and zero trust: the edge checks, the service decides
  19. Workloads · 18Event-driven identity: Kafka principals, ACLs and replay
  20. Workloads · 19Cloud IAM and secretless deployment: roles, federation and no stored keys
  21. Workloads · 20External SaaS, webhooks and trust: calls that cross company lines
  22. Workloads · 21Private controlled environments: what private networking does and does not secure
  23. AI-native · 22Authenticating to model providers: keys, gateways and cloud IAM
  24. AI-native · 23MCP identity and authorization: discovery is not permission
  25. AI-native · 24RAG and retrieval authorization: only what this caller may read
  26. AI-native · 25Agents as principals and delegates: whose authority is this?
  27. AI-native · 26Agent-to-agent trust: identity, capabilities and forwarded authority
  28. AI-native · 27Coding agents and CI: repository scopes, OIDC and no production keys
  29. Operations · 28Auditing and observability of access: decisions you can prove later
  30. Operations · 29Threat modeling and testing: the negative tests that prove access control
  31. Operations · 30Operational lifecycles: rotation, revocation and outages
  32. Reference · 31Standards, frameworks and products: what each one is, and what it is not
  33. Reference · 32Architecture decision playbooks: choosing an auth strategy
  34. ReferenceGlossary
  35. AboutAbout this site and its sources
Workloads · 20

External SaaS, webhooks and trust: calls that cross company lines

Outbound OAuth integrations, signed webhooks with replay protection, client authentication, secret rotation, rate limits, callbacks from providers, inbound and outbound policy, and reviews of third-party access.

You will understand
How a webhook receiver proves a callback came from the vendor, was not changed, and is not an old message sent again.
You will be able to build
A signature check with a timestamp window, constant-time comparison, duplicate detection and two secrets during rotation.
You will keep apart
Calls you make out to a vendor, calls a vendor makes in to you, and the review of what each vendor may see.

Roof reports are slow. When the assessment service asks the roof data provider about PROP-2207 for series case UW-004, the vendor does not answer at once; it queues the job and, minutes later, sends an HTTP POST to the insurer: "report ready, property PROP-2207, evidence EV-ROOF-0412, provider roof age 22 years". That figure, against 9 years on the application, is what rule R-ROOF-03 escalates to an underwriter.

The endpoint that receives that POST is on the internet, because the vendor is. Anyone who learns its URL can send it a request that looks the same. The first version in the design review accepted any well-formed JSON on the path /webhooks/roof-vendor, on the reasoning that the URL is long and unlisted. That is the mistake this page is about, shown here so the correction has something to correct. A forged callback that says "roof age 9 years" for a 22-year-old roof would remove the very discrepancy the underwriter needs to see. A real callback captured once and sent again a week later would overwrite a newer report with an older one.

So the receiving side has three questions, and they are the subject of this page: did this message come from the vendor, is it exactly what the vendor sent, and has it been processed before? The sending side has its own: when the assessment service calls the vendor, with what credential, to which hosts, at what rate, and who reviewed what the vendor can see?

Two directions across a company line#

An outbound integration is a call your system makes to another company's API: the assessment service asking the roof data provider for a report. A webhook is the reverse: an HTTP request the other company's system makes to an endpoint you published, to tell you that something happened. Both cross a trust boundary that no network control of yours covers end to end, and each direction needs its own proof.

Plain English. Outbound, you prove to the vendor who you are. Inbound, the vendor proves to you who it is. A shared secret can do the second job, but only if your code checks it on every message, in a way that cannot be fooled by timing or by replay.
Before AI. Payment notifications, shipping status callbacks, a CI server pinging a chat tool: backend engineers have received webhooks for years, and the checks below are the ones that payment integrations made common. Nothing about agents changes them. What changes is that an agent's evidence (here, a roof age) may arrive by webhook, so a forged callback becomes a forged input to a recommendation.

The smallest primitive: an HMAC over the exact bytes#

The sender and receiver share a random secret. For each delivery the sender computes an HMAC (a keyed hash: only someone with the secret can produce the right value) over the request body, and puts the result in a header. The receiver recomputes it over the bytes it received and compares. A webhook signature is that header value.

Product (GitHub webhooks, as documented on 2026-11-18): "The hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header"; it starts with sha256= followed by the hex HMAC-SHA256 of the body keyed by the webhook secret. GitHub's page adds three rules: use the raw body ("Make sure that the payload and headers are not modified before verification"), compare in constant time, not with ==, and keep the secret, "a random string of text with high entropy", out of code.

The constant-time rule exists because an ordinary string comparison stops at the first different character, so its running time leaks how much of a guess was right. Python documentation (hmac, read 2026-11-18): compare_digest "uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behaviour", and the hexdigest() notes recommend it "instead of the == operator". This teaching sketch shows the GitHub shape. It is standard-library Python, run in a scratch folder with a fake secret; in production, use the provider's maintained library or your framework's verified helper.

import hashlib
import hmac


def verify_github(secret: bytes, raw_body: bytes, header: str) -> bool:
    """GitHub shape: X-Hub-Signature-256 = "sha256=" + hex HMAC-SHA256 of the raw body."""
    expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)


if __name__ == "__main__":
    secret = b"DEMO-GITHUB-WEBHOOK-SECRET-not-a-secret"
    body = b'{"action":"opened","number":42}'
    good = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    print("signed body:          ", verify_github(secret, body, good))
    print("re-serialized body:   ", verify_github(secret, b'{"action": "opened", "number": 42}', good))
    print("same body, no window: ", verify_github(secret, body, good), "(nothing here says when it was sent)")
signed body:           True
re-serialized body:    False
same body, no window:  True (nothing here says when it was sent)

The second line is the raw-body rule in action: the same JSON with different spacing fails, so a framework that parses and re-serializes the body before your check breaks verification. The third line is the gap: GitHub's validation page states no timestamp or replay check, so a captured delivery verifies forever. Closing that gap needs a timestamp inside the signed content.

Replay protection: a signed timestamp and a message id#

Replay protection means a receiver rejects a genuine message that is sent again, either by an attacker who captured it or by an accidental resend. It needs two pieces: a timestamp that the signature covers, so an old message cannot be passed off as new, and a message id the receiver remembers, so the same message is processed once.

Pattern (Standard Webhooks, read 2026-11-18): an open set of guidelines with libraries, maintained by a community steering committee, which says "Every webhook implementation needs to protect themselves and their users from SSRF, spoofing, and replay attacks." Its headers are webhook-id, webhook-timestamp (an "integer unix timestamp (seconds since epoch)") and webhook-signature, "a space delimited list of signatures". The symmetric scheme v1 signs msg_id.timestamp.payload with HMAC-SHA256 and base64-encodes the result; secrets are base64-encoded with a whsec_ prefix, between 24 and 64 bytes. Receivers verify the timestamp is "within some allowable tolerance of the current timestamp to prevent replay attacks" (no number is given), "Use the webhook-id header as an idempotency key", and compare in constant time. The asymmetric scheme is now v2a (Ed25519 over the SHA-256 hash of the content); the earlier v1a "has been deprecated in favor of v2a", and "Producers should send v2a instead."

Product (Stripe webhooks, as documented on 2026-11-18): the Stripe-Signature header carries t (the signing timestamp) and one or more v1 entries, each an HMAC-SHA256 over the timestamp, a dot and "the unmodified HTTP request body"; integrations "must accept unknown entries". Stripe's libraries "have a default tolerance of 5 minutes between the timestamp and the current time", and the page warns: "Don't use a tolerance value of 0. Using a tolerance value of 0 disables the recency check entirely." Header entries named secret, destination and payload "aren't covered by the HMAC"; "Only a valid v1 signature authenticates the request".

The insurance example: verifying the roof vendor's callback#

The roof data provider in the example is a stand-in, and the example's code does not include a webhook endpoint. The sketch below is written for this page in the Standard Webhooks v1 shape, with the example's property and evidence ids. It demonstrates four checks in order: freshness of the signed timestamp, the signature against every active secret, constant-time comparison, and duplicate ids. A successful run proves the sketch rejects the six bad deliveries it was given. It does not prove a production receiver: it keeps seen ids in process memory, takes the secret as raw bytes (Standard Webhooks secrets arrive base64-encoded after whsec_), and parses no JSON. Teaching sketch; use the provider's maintained library.

import base64
import hashlib
import hmac

TOLERANCE_S = 300          # illustrative; take the value from the provider's documentation
SEEN_IDS: set[str] = set() # in production: a shared store with expiry, not process memory


def sign(secret: bytes, msg_id: str, ts: int, body: bytes) -> str:
    """Producer side, Standard Webhooks v1 shape: base64(HMAC-SHA256(secret, "id.ts.body"))."""
    mac = hmac.new(secret, msg_id.encode() + b"." + str(ts).encode() + b"." + body, hashlib.sha256)
    return "v1," + base64.b64encode(mac.digest()).decode()


def verify(secrets: list[bytes], headers: dict[str, str], body: bytes, now: int) -> tuple[bool, str]:
    """Receiver side: freshness, then signature against every active secret, then duplicate check."""
    msg_id, ts_raw = headers.get("webhook-id", ""), headers.get("webhook-timestamp", "")
    if not msg_id or not ts_raw.isdigit():
        return False, "missing id or timestamp"
    ts = int(ts_raw)
    if abs(now - ts) > TOLERANCE_S:
        return False, f"timestamp outside tolerance ({now - ts} s old)"
    offered = [s for s in headers.get("webhook-signature", "").split(" ") if s.startswith("v1,")]
    expected = [sign(k, msg_id, ts, body) for k in secrets]    # two secrets during a rotation
    if not any(hmac.compare_digest(o, e) for o in offered for e in expected):
        return False, "no signature matches an active secret"
    if msg_id in SEEN_IDS:
        return False, "duplicate webhook-id (replay or retry): already processed"
    SEEN_IDS.add(msg_id)
    return True, "verified"


if __name__ == "__main__":
    old = b"DEMO-WEBHOOK-SECRET-OLD-not-a-secret"
    new = b"DEMO-WEBHOOK-SECRET-NEW-not-a-secret"
    now = 1_794_992_400                       # 2026-11-18T09:00:00Z, the example's simulated clock
    body = b'{"type":"roof_report.ready","property_id":"PROP-2207","evidence_id":"EV-ROOF-0412"}'

    def hdrs(secret: bytes, msg_id: str, ts: int, payload: bytes = body) -> dict[str, str]:
        return {"webhook-id": msg_id, "webhook-timestamp": str(ts),
                "webhook-signature": sign(secret, msg_id, ts, payload)}

    cases = [
        ("valid delivery", [old], hdrs(old, "msg_01", now - 4), body),
        ("same delivery again", [old], hdrs(old, "msg_01", now - 4), body),
        ("body changed in transit", [old], hdrs(old, "msg_02", now - 2), body.replace(b"2207", b"3104")),
        ("captured, replayed 1 h later", [old], hdrs(old, "msg_03", now - 3600), body),
        ("signed with an unknown secret", [old], hdrs(b"guess", "msg_04", now), body),
        ("rotation: new secret, both active", [old, new], hdrs(new, "msg_05", now), body),
        ("rotation over: old secret only", [new], hdrs(old, "msg_06", now), body),
    ]
    for name, active, h, payload in cases:
        ok, why = verify(active, h, payload, now)
        print(f"{name:<34} {'ACCEPT' if ok else 'REJECT'}  {why}")

Run in a scratch folder on 2026-11-18 with /opt/homebrew/bin/python3 -I verify_webhook.py:

valid delivery                     ACCEPT  verified
same delivery again                REJECT  duplicate webhook-id (replay or retry): already processed
body changed in transit            REJECT  no signature matches an active secret
captured, replayed 1 h later       REJECT  timestamp outside tolerance (3600 s old)
signed with an unknown secret      REJECT  no signature matches an active secret
rotation: new secret, both active  ACCEPT  verified
rotation over: old secret only     REJECT  no signature matches an active secret

Notice the order of checks. The cheap timestamp check runs first, so a flood of stale messages costs no HMAC work. The duplicate check runs after the signature, so an attacker cannot fill the seen-id store with ids they made up. The 300-second window is an illustrative value for this sketch; Standard Webhooks gives no number, and Stripe documents its libraries' default as 5 minutes. The two rotation lines show why the receiver holds a list of secrets: during a change it accepts either, and after the change only the new one.

Diagram: The roof vendor calls back · verify, match, then fetch with our own credential

Time runs down the page. The assessment service asks the vendor for a report with its outbound credential and remembers the outstanding job. Minutes later the vendor POSTs a signed callback. The webhook receiver checks the timestamp window, the HMAC over the raw body against each active secret in constant time, and the webhook-id against ids already processed. A verified callback is only a notification: the service matches it to the outstanding job for PROP-2207 and fetches the report from the vendor's API itself. The agent's later request for the evidence is still decided on SUB-1004 by the PDP.

  1. Assessment service to Roof data provider: request report · PROP-2207 (outbound credential). An outbound call with the strongest credential the vendor offers, to an allowlisted host, within a rate limit.
  2. Roof data provider to Webhook receiver: POST callback · webhook-id, timestamp, signature. The vendor's delivery: a notification that the report is ready, signed over id, timestamp and raw body.
  3. Webhook receiver: window · HMAC in constant time · id not seen. Timestamp within tolerance, signature matches an active secret (two during rotation), id not already processed. Any failure: reject, change nothing.
  4. Webhook receiver to Assessment service: verified notification · match outstanding job. The content is a claim. It must correspond to a job the service actually requested.
  5. Assessment service to Roof data provider: GET report (own credential). The evidence comes from the vendor's API, not from the callback body.
  6. Assessment service to Policy decision point: later: may this caller read SUB-1004?. When the underwriting agent asks for the assessment, the business decision is made on the record, as always.

A verified callback is still only a notification. This site's recommendation: treat its content as a claim and do two things before it becomes evidence. First, match it to a request the assessment service actually made: an outstanding job for PROP-2207, not a property nobody asked about. Standard practice in a neighboring protocol says the same; Standard (A2A 1.0.0, read 2026-11-18): clients receiving push notifications "SHOULD verify the task ID in the payload matches an expected task" and "SHOULD process notifications idempotently". Second, fetch the report itself from the vendor's API with the assessment service's own outbound credential, rather than storing roof ages from the callback body. Then a stolen webhook secret lets an attacker send "something is ready" messages, not roof ages. The evidence EV-ROOF-0412 that reaches the underwriting agent comes from the fetch, and the agent's later request for it is still authorized on the submission by the policy decision point.

What this is not. A2A push notifications and agent-to-agent messages are a protocol of their own (https://a2a.sammuthu.com, and A2A trust for the auth side). Where the vendor key is stored is on API keys, and how the service reads it with no cloud key on Cloud IAM.

Outbound: calling the vendor with the right credential#

The assessment service's call to the vendor is the outbound integration, and its credential depends on what the vendor offers.

If the vendor offers only an API key, the design on API keys applies: a restricted key in a secrets manager, read by one service, used after authorization. If the vendor offers OAuth, the service is a confidential client using client credentials: it authenticates to the vendor's authorization server and receives a short-lived access token for the vendor's API. Standard (RFC 9700, read 2026-11-18): authorization servers "SHOULD enforce client authentication if it is feasible", and "It is RECOMMENDED to use asymmetric cryptography for client authentication", such as mutual TLS or private_key_jwt; with a private key, the vendor stores only a public key. Flows and token handling are on OAuth and OIDC.

Some integrations act for a person or an organization instead of for the service: an administrator at the insurer authorizes a SaaS tool once, and the integration keeps working afterwards. That pattern produces a refresh token, and where it lives decides the risk. Standard (RFC 6749, read 2026-11-18): refresh tokens are "intended for use only with authorization servers". This site's recommendation: keep refresh tokens server-side in the secrets manager, encrypted, readable only by the integration's workload, never in a browser, a log or model-visible context. Standard (RFC 9700): "Refresh tokens for public clients MUST be sender-constrained or use refresh token rotation." A confidential server-side client has a stronger position to begin with, which is one more reason the integration runs on the server.

Two more outbound controls are often missing. Rate limits: your calls count against the vendor's quota, and an agent that retries in a loop can exhaust it for every underwriter; cap calls per run and per submission in the assessment service. Egress allowlist: the assessment service may open connections only to the vendor's documented API host. Guideline (OWASP API Security Top 10 2023, API10 Unsafe Consumption of APIs, read 2026-11-18): "Developers tend to trust data received from third-party APIs more than user input"; prevention includes TLS for all API interactions, validating data from integrated APIs, and "Maintain an allowlist of well-known locations integrated APIs may redirect yours to: do not blindly follow redirects". The vulnerability list also names missing timeouts for third-party interactions.

Diagram: Inbound and outbound policy · what crosses the company line, in each direction

Two lanes, one per direction. Outbound, the assessment service authenticates to the vendor, reaches only allowlisted hosts and stays within rate limits and timeouts. Inbound, the vendor authenticates to the insurer by a message signature on one endpoint, and the content is confirmed before use. Both directions meet in the third-party access review, which decides whether the vendor keeps the access at all.

  1. Outbound · we call the vendor
    1. credential from the secrets manager: The strongest credential the vendor offers, held by one service.
    2. egress allowlist, rate limit, timeout: Connections only to the vendor's documented host; capped calls per run; no blind redirects.
  2. Inbound · the vendor calls us
    1. one endpoint, signed deliveries: The vendor proves itself per message; an IP allowlist is extra, not proof.
    2. window, dedupe, then confirm: Fresh, unique, verified, matched to an outstanding request, then data fetched outbound.
  3. Both directions
    1. third-party access review: What data leaves, what the vendor reaches, which credentials exist, and how to revoke all of them in one change.

The two lanes are deliberately asymmetric. Outbound, the insurer controls the credential, the destination and the rate. Inbound, the insurer controls only the endpoint, the verification and what it does with the message, so the message is confirmed before it becomes evidence. Both lanes end in the same place: a person who decides, on a schedule, whether this vendor keeps the access.

When you are the sender#

The insurer may also send webhooks, for example notifying a brokerage's system that quote Q-5531 changed status. Then the duties flip. Standard (A2A 1.0.0): agents "SHOULD validate webhook URLs to prevent SSRF", rejecting private ranges such as 10.0.0.0/8 and 192.168.0.0/16, localhost and link-local addresses. Pattern (Standard Webhooks): "prevent the webhooks from calling into internal networks and services." A brokerage that registers http://169.254.169.254/ as its callback URL should get a validation error, not your cloud credentials (see the metadata service on Cloud IAM). The payload names identifiers and states; it never carries a token, and the tenant boundary applies: brk-north receives events about its own quotes only, decided on the record like every other read.

Secret rotation with two valid secrets#

A webhook secret leaks the same way any secret does, and rotation must not drop callbacks in between. The method is an overlap: for a period the sender signs with both the old and the new secret, and the receiver accepts a match with either. Pattern (Standard Webhooks): during rotation the producer signs with the current and an old key for a limited period and sends both signatures; consumers "can try to verify each signature until one matches". Product (Stripe): rolling an endpoint secret can delay the old secret's expiry by up to 7 days, with one signature per active secret.

The order on the receiving side is the same every time: add the new secret to the receiver's list; tell the vendor to start signing with it; confirm deliveries verify against the new secret; remove the old secret from the list; confirm the vendor stopped using it. The sketch's last two lines are the evidence that the final step took effect.

Vendor trust and third-party access reviews#

Signatures and tokens answer "is this the vendor?". They do not answer "should this vendor have this access at all?". A third-party access review is a periodic check, by a named owner, of what each outside company can reach in your systems and what data you send it, ending in keep, narrow or remove.

For the roof data provider, the review asks concrete questions. What does the insurer send it? Property ids and addresses for roof lookups, not broker or underwriter identities. What can it reach? One webhook endpoint, through one secret; nothing inside the network. What credentials exist in each direction, who owns them, and when did each last rotate? If the vendor delivers files into the insurer's cloud account, which role does it assume and is that role protected against a confused deputy (AWS documents ExternalId for this, see Cloud IAM)? Does the vendor's own security posture still meet the bar, as API10 asks? The review belongs in the same governance cycle as people's access reviews, with the same evidence (see Governance).

In a coding agent. A coding agent's integrations are third parties too: the repository's GitHub App, a CI provider, a package registry. The same review applies, and GitHub's signed webhooks reach CI with X-Hub-Signature-256. Coding agents covers the repository side.

Architecture choice#

SituationSimplest credible optionGrow whenAlternatives
Vendor sends callbacks, HMAC offeredVerify signature over the raw body, timestamp window, id dedupe, then fetch the dataVendor offers asymmetric signaturesStandard Webhooks v2a; mTLS on the endpoint
Vendor signs the body only (no timestamp)Signature plus id dedupe plus "notification only, fetch the data"Replays matter for the businessAsk the vendor for signed timestamps
Outbound to a vendor with OAuthClient credentials, asymmetric client authenticationVendor needs per-user consentAuthorization code once, refresh token server-side
Outbound to a vendor with keys onlyRestricted key in a secrets managerVendor adds OAuthSee API keys
You send webhooks to customersStandard Webhooks shape, SSRF-validated URLs, tenant-scoped eventsMany customers, many endpointsA managed webhook delivery service

This site's recommendation: verify every inbound callback before parsing it, treat its content as a claim to be confirmed, keep outbound credentials in one service with an egress allowlist and rate limits, rotate secrets with an overlap, and review every vendor's access on a schedule with a named owner.

Security notes#

Security note. Verify the signature before parsing JSON. A parser bug reached by an unauthenticated request is exposed to the whole internet.
Security note. An IP allowlist for a vendor's webhook senders is defense in depth, not proof. Stripe documents both IP allowlisting and signature verification; keep the signature as the control.
Production pitfall. Middleware that decompresses, re-encodes or re-serializes the body before your handler sees it breaks every signature. Capture the raw bytes at the edge of the handler.
Security note. Respond quickly with a 2xx after verification and process asynchronously; a slow endpoint causes vendor retries, which arrive with new timestamps; deduplicate on the message id the sender documents as stable (Standard Webhooks recommends webhook-id as the idempotency key).

Monday checklist#

  1. List every inbound webhook endpoint: sender, verification method, timestamp window, duplicate handling, owner.
  2. Find any receiver that compares signatures with == or verifies a re-serialized body; fix both.
  3. Confirm each callback is matched to an outstanding request before it changes data.
  4. List every outbound integration with its credential type, storage place, rotation date, rate limit and allowed hosts.
  5. Validate customer-registered callback URLs against private, loopback and link-local ranges.
  6. Schedule the third-party access review for each vendor, with a named owner and the questions above.

Exercises#

  1. The vendor's callback includes the roof age. Why does the example fetch the report again instead of using it?
AnswerA stolen webhook secret then forges nothing that matters

The fetch uses the assessment service's own outbound credential to the vendor's API. A forged but validly signed callback can only say "ready"; the roof age comes from the vendor's API over a channel the insurer authenticated.

  1. A colleague sets the timestamp tolerance to 0 "for maximum security" in a library that treats 0 as a setting. What happens with Stripe's library?
AnswerThe recency check turns off

Stripe documents that a tolerance of 0 disables the recency check entirely, so old deliveries are accepted. Read each library's semantics; use a small positive window and synchronized clocks.

  1. During rotation, the receiver removes the old secret before the vendor switches. What do you see?
AnswerEvery delivery is rejected until the vendor switches

All callbacks fail verification, the vendor retries, and reports pile up. Keep both secrets active until deliveries verify against the new one, then remove the old.

Advanced perspective#

Symmetric or asymmetric webhook signaturesA shared secret on both sides against a public key on yours

With HMAC, the receiver holds the same secret the sender uses. Anyone who reads it from the receiver's configuration can sign deliveries, and a vendor with many customers must keep a secret per endpoint. Asymmetric signatures (Standard Webhooks v2a, Ed25519) put only a public key on the receiver: a leak of the receiver's configuration lets nobody sign. Standard Webhooks deprecated its earlier asymmetric scheme v1a, which "signed the content itself (without an endpoint ID) and required a unique key pair per endpoint", in favor of v2a, which "works with KMS and HSM signers".

The cost is verification code and key distribution: the receiver needs the vendor's current public keys and a way to learn about rotations. The verification rules stay the same: timestamp window, id dedupe, raw body. When a vendor offers both, prefer asymmetric if your library supports it; when it offers only HMAC, keep the secret in the secrets manager and give the receiver read access to that secret alone.

Duplicate detection at scaleHow long to remember ids, and where

The seen-id store has to cover the timestamp window and a margin, because a delivery outside the window is rejected anyway. That bounds its size: ids older than the window plus margin can expire. In a service with several instances, the store must be shared (a database table with a unique constraint on the id, or a cache with atomic set-if-absent), or two instances will each accept the same delivery once.

Retries complicate the picture. Stripe documents that retries get a new signature and timestamp; Standard Webhooks recommends the webhook-id header as the idempotency key, which only works if the sender keeps it the same for every attempt at one message; check that in the sender's documentation. A receiver that keys deduplication on something the sender changes per attempt will process retries twice. Business idempotency belongs downstream too: storing a roof report for PROP-2207 should be an upsert keyed on the vendor's report id, so even a duplicate that slips past changes nothing.

Other ways a sender can authenticatemTLS, OAuth tokens, and what each leaves open

Signatures are not the only option. A vendor can present a client certificate on a mutual TLS connection to the webhook endpoint (see TLS and PKI): that authenticates the connection, but the receiver still needs a freshness and duplicate check at the message level, and the certificate proves the vendor's machine, not the content of a single message stored later. A vendor can also obtain an OAuth access token from the insurer's authorization server and send it as a bearer token; A2A's push notifications work this way, through PushNotificationConfig.authentication, and A2A states that clients "MUST validate webhook authenticity using the provided authentication credentials". That gives audience-bound, expiring credentials, at the cost of running an authorization server the vendor can reach.

Message signatures have one property the other two lack: the proof travels with the message. A signed delivery can be stored and re-verified during an incident. This site's recommendation for evidence that feeds an underwriting recommendation: a message-level signature at least, with transport authentication as an addition where the vendor supports it.

What a vendor review should produceEvidence, not a questionnaire filed and forgotten

A review that ends in "approved" without evidence does not survive the next audit. Useful outputs are concrete: the list of data fields sent to the vendor, checked against what the integration actually sends (from logs, redacted); the list of credentials in both directions with owners and last rotation; the endpoints and roles the vendor can reach; the incident contact on both sides; and the exit plan, meaning how to revoke every credential and stop every flow in one change.

The last item is the one most often missing. When a vendor relationship ends, the outbound key, the webhook secret, any cross-account role and any refresh token must all be revoked together, the same way a leaver's accounts are (see Operations for emergency revocation). A vendor whose access cannot be removed in one change has access you do not fully control.

In one breath#

Calls across company lines need proof in both directions. Inbound, a webhook receiver checks a signature over the exact bytes, in constant time, inside a signed timestamp window, and remembers message ids, holding two secrets during a rotation; even then, a callback is a claim to match against an outstanding request and confirm through the vendor's API. Outbound, the service uses the strongest credential the vendor offers, from a secrets manager, to allowed hosts only, within rate limits, and every vendor's access is reviewed on a schedule by a named owner.

The roof vendor can now reach exactly one endpoint, and the assessment service can reach exactly one vendor host. Many organizations go further and put all of this inside private networks, with private endpoints, controlled egress, an internal certificate authority and gateways in front of everything. What those controls add, and the risk each one still leaves behind, is the subject of Private environments.