WebRiskOps

Automation code examples

Use Automation code examples to run placeholder-safe scanner postbacks, webhook target setup, ticket export approval, status polling, webhook signature verification and idempotent retries.

Developers and integration admins

Feature availability

Product, package, provider and deployment boundaries for this page.

Available from
Current documentation
Providers
apiwebhookticket-exportsscanner
Deployment modes
cloudself-hostedwebhook-only

Code examples

Copy-safe examples use placeholder values only.

cURL submit scanner resultscurl
curl -X POST "https://app.example.test/api/scanner/results" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}" \
  -H "Idempotency-Key: scan-run-example-123-attempt-1" \
  -d '{"scanRunId":123,"status":"completed","page":{"url":"https://example.test","normalizedUrl":"https://example.test/","statusCode":200,"pageType":"home","responseHeaders":{}},"artifacts":{"screenshotPath":"artifacts/example-home.png"},"issues":[]}'
cURL create ticket export webhook targetcurl
curl -X POST "https://app.example.test/api/ticket-export-targets" \
  -H "Authorization: Bearer ${WEBRISKOPS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: target-example-123" \
  -d '{"provider_key":"generic_webhook","base_url":"https://hooks.example.test/webriskops","deployment_mode":"webhook-only","name":"Example webhook target"}'
JavaScript approve ticket exportjavascript
await fetch("https://app.example.test/api/ticket-exports/example-export-id/approve", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WEBRISKOPS_API_TOKEN}`,
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "approve-ticket-export-example-123"
  },
  body: JSON.stringify({ target_id: "target_example_123" })
});
JavaScript poll export statusjavascript
const response = await fetch("https://app.example.test/api/ticket-exports/example-export-id", {
  headers: {
    "Authorization": `Bearer ${process.env.WEBRISKOPS_API_TOKEN}`,
    "Accept": "application/json"
  }
});
const exportStatus = await response.json();
console.log(exportStatus.status === "retry_scheduled" ? exportStatus.retry_after_seconds : exportStatus.status);
PHP verify outbound webhookphp
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$nonce.'.'.$body, getenv('WEBRISKOPS_WEBHOOK_SECRET'));
if (! hash_equals($expected, $receivedSignature)) {
    throw new RuntimeException('Invalid example webhook signature.');
}
PHP retry with idempotency keyphp
$headers = [
    'Authorization' => 'Bearer '.getenv('WEBRISKOPS_API_TOKEN'),
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Idempotency-Key' => 'retry-example-123',
];
// Reuse this example idempotency key only when retrying the same logical request.

Before running automation snippets

Use these snippets after one placeholder request works from Request and response examples. They cover scanner postbacks, generic webhook target setup, ticket export approval, ticket export status polling, outbound webhook signature verification and idempotent retries without using production credentials.

  • Start from placeholder base URLs, IDs, tokens and secrets; replace them only in your private environment.
  • Keep copied examples scoped to the customer account, plan and provider target that is allowed to run the action.
  • Do not paste real customer evidence, payment data, credentials, private artifact paths or provider secrets into example payloads.
  • Keep `${WEBRISKOPS_API_TOKEN}`, `${WRO_SCANNER_SHARED_SECRET}` and `${WEBRISKOPS_WEBHOOK_SECRET}` in environment configuration, not in tickets, screenshots or shared notes.

Choose and run an automation example

Follow the path `Request and response examples → Automation snippet → Placeholder replacement → Run or poll → Retry or continue`.

  1. Open Request and response examples and confirm a single placeholder request works before copying a larger automation snippet. Result: the automation starts from a known-good auth, JSON and response pattern.
  2. Use cURL submit scanner results only for `POST /api/scanner/results` with `X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}` and `Idempotency-Key`. Result: scanner retries stay tied to the same `scanRunId` and attempt.
  3. Use cURL create ticket export webhook target only when the account is allowed to configure a `generic_webhook` target. Result: `provider_key`, `base_url` and `deployment_mode` are set before ticket approval.
  4. Use JavaScript approve ticket export only after the target is active and the ticket preview is safe. Result: `target_id` approves the prepared export without placing provider secrets in the payload.
  5. Use JavaScript poll export status until the response is `exported`, `blocked`, `failed` or `retry_scheduled`. Result: UI or automation waits for WebRiskOps state instead of creating duplicate provider tasks.
  6. Use PHP verify outbound webhook when receiving `X-WebRiskOps-Signature`, `X-WebRiskOps-Timestamp` and `X-WebRiskOps-Nonce`. Result: unsigned or replayed ticket export payloads stop with `WEBHOOK_SIGNATURE_INVALID`.
  7. Use PHP retry with idempotency key when retrying the same logical request after a transient `429` or `5xx`. Result: the same `Idempotency-Key` is reused only when the payload meaning has not changed.
  8. Replace every `example` ID, host and environment variable in a private environment. Result: public docs, tickets and screenshots do not expose production tokens, secrets or customer data.
  9. If a snippet returns `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_FAILED`, `RATE_LIMITED` or `SIGNATURE_INVALID`, stop and open Errors, idempotency, retries and rate limits. Result: the next attempt changes the right input instead of retrying blindly.
  10. Continue to API ticket export webhooks or Webhook export after the automation succeeds. Result: signed delivery, retry behavior and downstream tracking stay tied to the same source export.

Configure scanner and target examples

Use the cURL examples when automation starts or connects a WebRiskOps workflow.

  • The scanner postback sends `POST /api/scanner/results`, `X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}`, `Accept: application/json`, `Idempotency-Key`, `scanRunId`, `status`, page fields, artifact paths and issues.
  • Scanner postbacks should return `202 Accepted`; `UNAUTHORIZED` means the scanner secret is missing or wrong, and `VALIDATION_FAILED` means the payload shape should be fixed before retrying.
  • The webhook target example creates a `generic_webhook` target with a placeholder `base_url`, `deployment_mode` and target name before a ticket export is approved.
  • Target setup should use `Authorization: Bearer ${WEBRISKOPS_API_TOKEN}` and keep receiver secrets outside the JSON payload.
  • If the target base URL is blocked, unsafe or unavailable, continue to Generic webhook automation setup before approving a ticket export.

Configure ticket export examples

Use the JavaScript and PHP examples after the ticket export target is configured.

  • The approval request posts to the prepared ticket export approval endpoint with `target_id` and `Idempotency-Key`.
  • The polling request reads the export status until it is `exported`, `blocked`, `failed` or `retry_scheduled`.
  • A `retry_scheduled` response should show `retry_after_seconds` or equivalent backoff state before the next poll.
  • Webhook receivers must verify `X-WebRiskOps-Signature`, `X-WebRiskOps-Timestamp`, `X-WebRiskOps-Nonce` and the raw body before writing downstream work.
  • Signature failures should stop with `WEBHOOK_SIGNATURE_INVALID`; validation or rate-limit failures should return a documented webhook error before any provider ticket is created.

Ready and blocked automation states

Use these states to decide whether copied code should keep running.

  • Ready scanner example means `POST /api/scanner/results` accepted the placeholder payload with `202 Accepted`.
  • Ready target example means the `generic_webhook` target stores the placeholder `base_url` and can be selected by a ticket export approval.
  • Ready export example means the approval request accepted `target_id`, and polling reaches `exported` or a documented terminal state.
  • Retry scheduled means the automation saw `retry_scheduled`, kept the same source identifiers and waited for the documented backoff before the next attempt.
  • Blocked automation means `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_FAILED`, `RATE_LIMITED`, `SIGNATURE_INVALID`, `WEBHOOK_SIGNATURE_INVALID` or an unsafe target URL still applies.

Continue after automation examples

After the placeholder automation succeeds, keep the code private and move to the endpoint-specific guide for production wiring. Use Authentication and headers for token or signing setup, Scanner results API for scanner payload shape, API ticket export webhooks for signed outbound delivery, Webhook export for provider behavior and Errors, idempotency, retries and rate limits for failed attempts.

Related documentation

Authentication and headersRequest and response examplesScanner results APIAPI ticket export webhooksErrors, idempotency, retries and rate limitsGeneric webhook automation setupWebhook export

Was this page helpful?

Feedback goes into the product documentation review queue.