iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A replay-safe Cypress Cloud receiver must authenticate the exact HTTP bytes Cypress sent, reject old timestamps, deduplicate deliveries, validate the event schema, and acknowledge quickly. Verify the X-Cypress-Signature header against ${timestamp}.${rawBody} with HMAC-SHA256 before parsing JSON; use a stable event ID for idempotency; and keep each attempt under Cypress Cloud’s 10-second timeout. This guide shows a framework-neutral TypeScript design, the delivery behavior you must handle, and the operational choices that keep retries from triggering duplicate side effects.
What must a Cypress Cloud webhook receiver guarantee?
Your endpoint should make five decisions in a fixed order: preserve the raw request body, verify authenticity and freshness, validate the event envelope, accept the event exactly once for your business purpose, and return an HTTP response directly. Cypress Cloud sends JSON POST requests with metadata in X-Cypress-* headers. A successful HTTP response means your service accepted responsibility; it does not mean Cypress will deliver only once.
- Capture bytes: retain the incoming body as a
Bufferor equivalent byte array before any JSON parser runs. - Authenticate: read the timestamp and signature headers, calculate the expected HMAC, and compare it in constant time.
- Check freshness: reject timestamps outside your configured tolerance to limit replay attacks.
- Validate: check the event name, event-version header, and event-specific JSON, including nullable fields.
- Deduplicate and dispatch: persist a stable event key or enqueue it with deduplication before performing non-idempotent work.
- Acknowledge: respond directly once durable acceptance is complete, without waiting for slow downstream jobs.
The official reference for headers, signatures, payloads, retry behavior, and configuration is Cypress Cloud’s Webhooks Integration documentation.
Recommended Free Tools
Which headers does Cypress Cloud send?
Use the headers as an envelope around the JSON body. Event and idempotency identifiers have different meanings, so do not substitute the per-attempt request ID for a deduplication key.
Popular on Amazon
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
| Header | Purpose | How to use it |
|---|---|---|
X-Cypress-Event |
Event name | Route to the correct schema and handler. |
X-Cypress-Event-Id |
Stable event identifier | Primary key for deduplication across retries and redelivery. |
X-Cypress-Event-Version |
Payload version | Choose the matching validator; reject or quarantine unsupported versions. |
X-Cypress-Request-Id |
Attempt identifier | Use for logs and tracing only; it changes on each delivery attempt. |
X-Cypress-Timestamp |
Signed Unix timestamp | Check freshness and include the exact value in HMAC input. |
X-Cypress-Idempotency-Key |
Stable retry key | Use as an alternative stable deduplication key when your design prefers it. |
X-Cypress-Signature |
sha256=<hex HMAC> |
Verify only when a signing secret is configured; fail closed when authentication is required and the header is missing. |
Keep the event ID, idempotency key, and request ID in structured logs. The first two identify the logical delivery; the last identifies a particular attempt.
How do I verify a Cypress signature in TypeScript?
Compute HMAC-SHA256 over the timestamp, a period, and the untouched request bytes. Parse JSON only after the signature and timestamp checks succeed. Cypress’s published sample is Node.js JavaScript rather than a framework-specific TypeScript recipe, so the raw-body capture API differs among Express, Fastify, NestJS, serverless adapters, and other frameworks.
Framework-neutral verification function
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyCypressRequest(
rawBody: Buffer,
timestampHeader: string | undefined,
signatureHeader: string | undefined,
secret: string,
nowSeconds = Math.floor(Date.now() / 1000),
toleranceSeconds = 300,
): void {
if (!timestampHeader || !signatureHeader) {
throw new Error("Missing Cypress signature headers");
}
const timestamp = Number(timestampHeader);
if (!Number.isInteger(timestamp)) {
throw new Error("Invalid Cypress timestamp");
}
if (Math.abs(nowSeconds - timestamp) > toleranceSeconds) {
throw new Error("Stale Cypress webhook");
}
const expected = createHmac("sha256", secret)
.update(`${timestampHeader}.${rawBody.toString("utf8")}`)
.digest("hex");
const supplied = signatureHeader.startsWith("sha256=")
? signatureHeader.slice("sha256=".length)
: "";
const expectedBytes = Buffer.from(expected, "utf8");
const suppliedBytes = Buffer.from(supplied, "utf8");
if (expectedBytes.length !== suppliedBytes.length ||
!timingSafeEqual(expectedBytes, suppliedBytes)) {
throw new Error("Invalid Cypress signature");
}
}The 300-second tolerance in this example is the window used by Cypress’s Node.js documentation example, not a universal security standard. Make the window an explicit policy for your environment, keep server clocks synchronized, and monitor clock drift. A smaller window reduces replay opportunity but increases failures when clocks or network paths are unreliable.
Preserve the body before JSON middleware
Many web frameworks consume the stream and expose only a parsed object. Re-serializing that object can change whitespace, escaping, key order, or number formatting, producing different bytes and therefore a different HMAC. Configure your framework to retain the raw bytes for this route, or place signature verification in the adapter that receives the original body. Do not call JSON.stringify(req.body) as a substitute.
If your service requires authenticated delivery, treat absent signing headers or an unset production secret as a configuration error and reject the request. Never log the secret, the complete authorization material, or sensitive payload fields merely to diagnose a failed signature.
How should timestamp checks stop replay attacks?
A valid HMAC proves that someone possessing the secret signed the message; it does not prove that the message is new. Compare the signed timestamp with the receiver’s current Unix time and reject values outside your configured tolerance before dispatching any work.
Also popular on Amazon
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
- Parse the header as an integer and reject malformed values.
- Use the exact timestamp string received in the HMAC input; do not normalize it before calculating the digest.
- Use an absolute difference so messages from either side of the clock are handled consistently.
- Synchronize hosts with a reliable time source and alert on significant drift.
- Continue to deduplicate even inside the freshness window, because a captured request can be replayed repeatedly while it remains fresh.
A timestamp check is not encryption. Cypress explicitly states that “A signing secret does not encrypt the payload.” Use HTTPS to protect confidentiality in transit; the signature supplies authenticity and integrity, not secrecy.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallHow do I deduplicate retries and redeliveries?
Design for at-least-once delivery. Store a durable record keyed by X-Cypress-Event-Id or X-Cypress-Idempotency-Key before causing a non-idempotent side effect, or enqueue the verified event in a system that provides equivalent deduplication.
Database-backed acceptance
Insert the stable key into a table with a unique constraint in the same transaction that records the work to be performed. If the insert conflicts, return success without repeating the side effect. The exact schema and transaction boundary are application choices; the important property is that acceptance and the duplicate check cannot race.
Durable queue acceptance
After verification and validation, publish an envelope containing the stable key, event name, version, headers needed for tracing, and the parsed payload. Configure the consumer or an inbox table to ignore a key it has already completed. A queue isolates the webhook request from slow APIs, but adds broker, retry, monitoring, and dead-letter operations.
Use X-Cypress-Request-Id for attempt-level diagnostics only. It changes on each attempt, so using it as the idempotency key would allow the same event to run repeatedly.
Which Cypress events and payload checks are required?
Accept only event types and versions your code understands. The documented event names are run.completed, run.accessibility.completed, and run.uiCoverage.completed.
Also popular on Amazon
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
| Event | Validation focus | Important interpretation |
|---|---|---|
run.completed |
Run identity, status, timestamps, counts, commit metadata, CI metadata, tags, and groups | Several values can be null; model them as nullable rather than assuming strings are always present. |
run.accessibility.completed |
Run envelope plus the nested accessibility report object |
Report-processing status is separate from the top-level run status. |
run.uiCoverage.completed |
Run envelope plus the nested uiCoverage report object |
Do not treat a UI Coverage report state as a replacement for the run’s overall state. |
Validate types, required identifiers, enum values, and maximum lengths with a schema library or equivalent handwritten checks. Preserve unknown fields when practical so a forward-compatible producer change does not destroy information, while still rejecting an event version your handler cannot safely interpret. Route malformed or unsupported messages to an inspection path rather than performing partial side effects.
What response and retry behavior must the endpoint handle?
Cypress retries transport failures and HTTP 408, 429, and 5xx responses with exponential backoff and jitter, for up to 10 total attempts: the initial delivery plus as many as nine retries. Completed 3xx responses and most other 4xx responses are treated as permanent failures, so return a deliberate status code instead of relying on a redirect or an accidental client error.
| Receiver result | Cypress behavior | Receiver guidance |
|---|---|---|
| 2xx success | Delivery is accepted. | Return only after durable acceptance or enqueueing. |
| Network/transport failure | Retried with backoff and jitter. | Keep the service publicly reachable and fail quickly when unavailable. |
| 408, 429, or 5xx | Retried, up to 10 total attempts. | Use these statuses for temporary inability, not permanent validation failures. |
| Most 4xx | Not retried. | Use for invalid signatures, stale timestamps, unsupported versions, or malformed payloads when you want the delivery marked failed. |
| 3xx | Not followed as a redirect. | Expose the final HTTPS endpoint directly; do not depend on canonicalization redirects. |
Each attempt has a 10-second timeout. Keep signature verification, validation, and durable acceptance comfortably below that limit. Cypress stores only the first 8 KB of your response body, which is a response-retention limit, not an inbound request-size limit; impose your own request-size limit appropriate to your service.
Test sends are not retried. Manual redelivery keeps the original event ID, so the same deduplication rule must protect both automatic retries and operator-triggered replay.
Should processing be synchronous or queued?
Choose based on how quickly you can make acceptance durable and how much downstream work follows.
| Approach | Advantages | Trade-offs | Use when |
|---|---|---|---|
| Synchronous | Fewer moving parts and immediate business processing. | Downstream latency can approach the 10-second timeout; transient dependencies can trigger retries. | Work is small, predictable, and transactionally coupled to the receiver. |
| Durable queue | Fast acknowledgment, isolation from slow services, and independent worker retries. | Requires queue operations, consumer idempotency, observability, and dead-letter handling. | Processing includes network calls, reports, notifications, or other variable-latency tasks. |
Whichever model you select, make the stable event key visible to every worker and side-effecting operation. A queue does not create exactly-once delivery by itself; it only gives you a durable place to apply an idempotency policy.
Also popular on Amazon
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
How do I configure a reachable and secure destination?
The destination must accept public HTTPS POST requests and respond directly. Cypress blocks private, loopback, and link-local destinations and does not follow redirects. A signing secret should contain at least 16 characters, must stay out of source control and logs, and is shown only once when configured.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsConfiguration checklist
- Create a publicly reachable endpoint with a stable HTTPS URL.
- Configure the signing secret in Cypress Cloud and your secret manager; do not hard-code it in TypeScript.
- Optionally configure a custom authorization header for destination-specific authentication. This is separate from HMAC signing.
- Set a request-size limit and reject unsupported content types before expensive processing.
- Allow the documented Cypress source traffic through your edge controls without exposing private administrative routes.
- Plan secret rotation as a coordinated change: Cypress rotation invalidates the old secret, so update the receiver and destination together.
- Use concise response bodies and include the event ID and request ID in logs for incident correlation.
A project can have up to five webhooks. Cypress’s custom-integration guidance also describes native and no-code destinations at Build custom integrations with Cypress webhooks. Many no-code tools cannot calculate HMAC over the original raw bytes, so confirm raw-body signature support before placing one in front of a protected receiver.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How should I test failure paths before production?
Test the receiver with captured raw bytes and controlled headers, then exercise the delivery behavior at the boundary.
- Send a valid body and matching timestamp/signature; confirm a single durable acceptance and a 2xx response.
- Change one byte of the body after generating the signature; confirm rejection.
- Change the timestamp, signature prefix, or secret; confirm rejection without parsing or side effects.
- Send an old timestamp and a future timestamp; confirm both are outside your stated tolerance.
- Deliver the same event twice with the same stable key; confirm the second request is acknowledged without repeating the side effect.
- Send each supported event with nullable fields set to
nulland verify the schema accepts documented nullability. - Send an unsupported event name or version; confirm it follows your permanent-failure or quarantine policy.
- Delay a downstream dependency and verify the receiver either queues safely or returns before the attempt timeout.
- Verify logs contain correlation identifiers but not the signing secret or unnecessary payload data.
Use the real framework adapter in these tests. A unit test around the HMAC function cannot reveal that production middleware discarded the raw body before your verifier ran.
What happens when grouped runs finish at different times?
For parallel or grouped runs, run.completed can be delayed by the Run Completion Delay. Cypress documents a 60-second default after the last known group finishes in this scenario. If your orchestration already knows that all expected groups have completed, the Run Completion API can skip the remaining delay; treat that as a workflow optimization, not a change to signature or idempotency rules.
Free tools Windows power users keep installed
One-click scans. No signup required.
What should observability and recovery look like?
Track counters for accepted events, duplicate keys, stale timestamps, invalid signatures, unsupported versions, schema failures, queue failures, and downstream completion. Include event ID, idempotency key, request ID, event name, version, and measured processing duration in structured logs. Avoid logging raw signed payloads by default when they may contain repository, CI, or user information.
Also popular on Amazon
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
For recovery, retain enough metadata to identify a failed event and safely reprocess it through the same verification and deduplication path. Never bypass the stable-key check just because an operator initiated the replay. Alert on repeated 5xx responses, rising timeout rates, clock drift, and unusual signature failures; these signals distinguish an unavailable dependency from a misconfigured secret or an attack.
Frequently Asked Questions
What happens if I rotate the Cypress signing secret while deliveries are in flight?
Rotation invalidates the old secret, so requests signed with it will fail after the change. Coordinate the update window, deploy the new secret to the receiver, and watch signature-failure logs; do not print either secret while diagnosing the transition.
Can a webhook signature hide credentials or test data from an observer?
No. HMAC authenticates and protects integrity but does not encrypt the JSON. Use HTTPS and apply normal payload-access controls, redaction, and retention policies for any sensitive CI or repository metadata.
Why did my endpoint receive the same event after an operator redelivered it?
Manual redelivery intentionally retains the original event identifier. Your acceptance store or queue inbox should therefore recognize it as the same logical event and return success without repeating side effects.
How many webhook destinations can one Cypress project have?
Cypress documents a limit of up to five webhooks per project. If you need more consumers, fan out from one verified receiver or queue rather than weakening authentication on multiple ad-hoc endpoints.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
