Request and response examples

Before copying examples

Use these examples when you need one safe request template before testing scanner postbacks, authenticated platform handoffs or outbound ticket export webhook receivers. Every snippet uses fictional hosts, IDs and environment variables so it can be copied into a private test environment before real credentials are added.

• Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
• Replace `app.example.test`, `example.test`, numeric IDs and environment variable names only in your private environment.
• Keep copied examples scoped to the endpoint, plan, token ability and provider target the customer is allowed to use.

Choose a safe request example

Follow the path `Authentication and headers → Endpoint page → Copy placeholder example → Send test request → Interpret response`.

1. Open Authentication and headers before copying a snippet. Result: the example uses the correct `Authorization`, `X-Scanner-Secret` or webhook signature header before any payload is sent.
2. Choose the cURL scanner postback only when you are testing `POST /api/scanner/results`. Result: the request includes `X-Scanner-Secret`, `Idempotency-Key`, `scanRunId`, `status`, page data, artifact references and issues.
3. Choose the JavaScript authenticated request only when the token has the route ability needed for the platform handoff. Result: `Authorization: Bearer ${WEBRISKOPS_API_TOKEN}` stays in an environment variable and does not appear in the body or URL.
4. Choose the PHP webhook verifier only when building a receiver for outbound ticket export webhooks. Result: `X-WebRiskOps-Signature`, `X-WebRiskOps-Timestamp`, `X-WebRiskOps-Nonce` and the raw body are checked before downstream work is created.
5. Replace every placeholder host, ID, token name and example payload field in a private test environment. Result: public docs, tickets and screenshots never expose production values.
6. Send `Content-Type: application/json` and `Accept: application/json` with JSON examples. Result: validation and error responses use the documented JSON shape.
7. Keep the same `Idempotency-Key` only when retrying the same logical request. Result: duplicate-safe endpoints and developer logs can identify repeated attempts.
8. Treat `202 Accepted`, `201 Created`, `204 No Content` or a 2xx webhook response as accepted. Result: the client stops retrying that attempt.
9. If the response is `401`, `403`, `422`, `429` or `5xx`, stop and open Errors, idempotency, retries and rate limits. Result: auth, ability, validation, rate-limit and transient failures are handled with the right next action.
10. Continue to Automation code examples after one request works. Result: retries, polling and ticket export approval examples start from a verified request template.

Copy the scanner result example

Use the cURL example for scanner postback testing.

• The endpoint is `POST /api/scanner/results`.
• The request uses `X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}`, `Content-Type: application/json`, `Accept: application/json` and `Idempotency-Key`.
• The payload includes `scanRunId`, `status`, `page.url`, `page.normalizedUrl`, `page.statusCode`, `page.pageType`, `artifacts.screenshotPath` and `issues`.
• A completed scanner postback should return `202 Accepted`.
• A missing shared secret returns `401 Unauthorized`, and malformed scanner payloads return `422 Validation failed`.

Copy the authenticated handoff example

Use the JavaScript example for token-authenticated API calls such as browser extension evidence capture.

• The endpoint is `POST /api/browser-extension/evidence-captures`.
• The bearer token should come from `WEBRISKOPS_API_TOKEN` and must have the route-specific ability.
• The payload includes `project_id`, `page_url`, optional page metadata and a safe `heading_outline`.
• Accepted platform handoffs return `201 Created` with the stored capture or diagnostic and a handoff object.
• Missing auth returns `401 Unauthorized`, insufficient token ability returns `403 Forbidden`, and invalid fields return `422 Validation failed`.

Copy the signed webhook verification example

Use the PHP example for outbound ticket export webhook receivers.

• Compute the expected value with `hash_hmac('sha256', $timestamp.'.'.$nonce.'.'.$body, getenv('WEBRISKOPS_WEBHOOK_SECRET'))`.
• Compare the expected value with the received `X-WebRiskOps-Signature` using `hash_equals`.
• Verify `X-WebRiskOps-Timestamp`, `X-WebRiskOps-Nonce` and replay protection before creating downstream work.
• Return 2xx only after the signed payload is accepted for processing.
• Return `WEBHOOK_SIGNATURE_INVALID`, `WEBHOOK_VALIDATION_FAILED` or `WEBHOOK_RATE_LIMITED` style responses from the receiver when signature, schema or rate-limit handling fails.

Continue after testing examples

After the first placeholder request succeeds, continue to Automation code examples for polling, retries and ticket export approval snippets. Use Scanner results API, Extension and platform handoffs or API ticket export webhooks when the example needs endpoint-specific fields, and use Errors, idempotency, retries and rate limits when a response is rejected.