Ticket export webhooks

Use Ticket export webhooks to verify signed ticket_export.requested deliveries with ticket-export.webhook.v1, X-WebRiskOps-Signature, replay protection and retry responses.

Developers and automation admins

Feature availability

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

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

Code examples

Copy-safe examples use placeholder values only.

Ticket export webhook JSON payloadjson

{
  "schema_version": "ticket-export.webhook.v1",
  "event": "ticket_export.requested",
  "idempotency_key": "generic-webhook-fingerprint-123",
  "replay_protection": {
    "timestamp": "1766203200",
    "nonce": "nonce_example_123",
    "signature_header": "X-WebRiskOps-Signature"
  },
  "attempt": 1,
  "target": {
    "id": 123,
    "provider_key": "generic_webhook"
  },
  "account": {
    "id": 456,
    "project_id": 789
  },
  "ticket_export": {
    "contract_version": "ticket-export.v1",
    "source": {
      "type": "report_issue",
      "record_id": 42,
      "title": "Checkout form drops validation state",
      "severity": "high",
      "category": "checkout_forms",
      "status": "open",
      "report_id": 12,
      "issue_id": 42,
      "fix_task_id": null,
      "fingerprint": "generic-webhook-issue-42",
      "affected_url": "https://store.example.test/checkout",
      "related_issue_ids": []
    },
    "title": "Fix checkout validation state",
    "summary": "The checkout form drops visible validation state after a failed payment attempt.",
    "business_impact": null,
    "reproduction_steps": [
      "Open checkout.",
      "Submit with an invalid card."
    ],
    "evidence_links": [
      {
        "label": "Issue evidence",
        "url": "https://app.example.test/evidence/generic-webhook-issue-42",
        "type": "report",
        "expires_at": null,
        "attachment_allowed": false
      }
    ],
    "remediation_snippet": null,
    "acceptance_criteria": [
      {
        "description": "Checkout validation remains visible after payment failure.",
        "evidence_required": true,
        "verification_hint": null,
        "source_reference": null
      }
    ],
    "labels": [
      "webriskops"
    ],
    "priority": "high",
    "assignee": null,
    "external_ticket_refs": [],
    "export_status": "draft"
  },
  "rendered_body": {
    "format": "markdown",
    "body": "Summary\nQueued generic webhook body.\nEvidence: https://app.example.test/evidence/generic-webhook-issue-42\n",
    "sections": [
      "summary",
      "evidence"
    ]
  }
}

Before receiving ticket export webhooks

Use this page when WebRiskOps sends a ticket export to a customer-owned generic webhook, Zapier, Make or n8n endpoint. The receiver verifies the signature, checks replay protection, accepts the provider-safe ticket payload and returns a response that lets WebRiskOps mark the export, retry it or show a blocked state.

Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
Configure the endpoint and signing secret through Generic webhook automation setup before testing delivery.
Keep raw screenshots, HTML snapshots, webhook secrets and private artifact paths out of downstream provider tasks.

Verify a signed ticket export delivery

Follow the path `Generic webhook automation setup → Signed ticket export delivery → Receiver duplicate guard → Provider task → Retry or fallback`.

Open Generic webhook automation setup and confirm the endpoint, signing secret and provider_key are ready. Result: WebRiskOps can send only to a customer-owned generic_webhook, webhook, zapier_webhook, make_webhook or n8n_webhook target.
Receive POST deliveries from WebRiskOps with Content-Type: application/json and no redirect requirement. Result: unsafe redirects are blocked before another endpoint receives ticket data.
Read X-WebRiskOps-Event and require ticket_export.requested. Result: the receiver ignores unrelated WebRiskOps events.
Read X-WebRiskOps-Schema and require ticket-export.webhook.v1. Result: payload parsing follows the expected schema_version.
Verify X-WebRiskOps-Signature by computing HMAC-SHA256 over X-WebRiskOps-Timestamp, X-WebRiskOps-Nonce and the raw body with the webhook signing secret. Result: invalid signatures return WEBHOOK_SIGNATURE_INVALID before downstream work is created.
Reject old timestamps, reused replay_protection.nonce values and mismatched X-WebRiskOps-Idempotency-Key values. Result: replayed or duplicate deliveries do not create duplicate tickets.
Parse target.provider_key, account.id, account.project_id, ticket_export and rendered_body. Result: the receiver can create provider-safe downstream work without raw private artifacts or secrets.
Return 2xx only after the payload is accepted for processing. Result: WebRiskOps records the delivery as exported and links the external reference to the same idempotency fingerprint.
Return 400 or 422 for schema issues, 401 or 403 for auth/signature issues, and 429 with Retry-After for rate limits. Result: WebRiskOps shows validation, auth or retry state without resending unsafe data.
Continue to Errors, idempotency, retries and rate limits or Webhook export after verification. Result: retry behavior, duplicate handling and portable fallback stay tied to the same ticket export source.

Configure webhook payload handling

Treat the WebRiskOps headers as the delivery envelope and the JSON body as the provider-neutral ticket export.

WebRiskOps sends `X-WebRiskOps-Event`, `X-WebRiskOps-Schema`, `X-WebRiskOps-Idempotency-Key`, `X-WebRiskOps-Timestamp`, `X-WebRiskOps-Nonce` and `X-WebRiskOps-Signature`.
Use the Ticket export webhook JSON payload example as the request body; the signature headers are sent outside the JSON body.
`schema_version` must be `ticket-export.webhook.v1`, and `event` must be `ticket_export.requested`.
`idempotency_key` should match `X-WebRiskOps-Idempotency-Key` and stay stable for the same export attempt retry.
`replay_protection.timestamp`, `replay_protection.nonce` and `replay_protection.signature_header` describe the signature inputs the receiver should validate.
`attempt` increments when WebRiskOps retries the same ticket export delivery.
`target.id` and `target.provider_key` identify the WebRiskOps integration target.
`account.id` and `account.project_id` identify the customer account and project scope without exposing account secrets.
`ticket_export` contains the provider-neutral ticket title, body, severity, labels, source identifiers and evidence-safe links.
`rendered_body` contains the formatted ticket body and sections prepared for downstream tools.

Ready ticket export webhook states

Continue only when the receiver can verify and deduplicate each delivery.

Endpoint ready means the target URL accepts HTTPS JSON POST requests and does not require redirects.
Signing ready means the receiver can compute the HMAC-SHA256 value from timestamp, nonce, raw body and the configured webhook secret.
Schema ready means `X-WebRiskOps-Schema` and `schema_version` both match ticket-export.webhook.v1.
Replay guard ready means old timestamps and reused replay_protection.nonce values are rejected before work is created.
Idempotency ready means `X-WebRiskOps-Idempotency-Key` and `idempotency_key` map to one logical ticket export.
Payload ready means ticket_export and rendered_body create downstream work without raw private artifacts, secrets or unredacted customer data.

Blocked ticket export webhook states

Blocked states should show the exact receiver or target configuration to fix.

`WEBHOOK_SIGNATURE_INVALID` means the receiver rejected `X-WebRiskOps-Signature`, timestamp, nonce or raw-body HMAC calculation.
`WEBHOOK_RATE_LIMITED` means the receiver returned 429 and should include `Retry-After` so WebRiskOps can retry automatically.
`WEBHOOK_VALIDATION_FAILED` means the receiver rejected the schema, event or required payload fields.
`generic_webhook_validation_failed` means the endpoint returned 400 or 422 for the signed ticket payload.
`generic_webhook_auth_failed` means the endpoint returned 401 or 403 for auth or signature handling.
`generic_webhook_redirect_blocked` means the endpoint redirected the request and must be replaced with the final safe HTTPS URL.
`generic_webhook_url_unsafe` means the target URL is not safe for automated outbound delivery.
`generic_webhook_secret_missing` means the target has no signing_secret, webhook_secret or secret credential available.

Continue after ticket export webhook setup

After the receiver returns 2xx for a signed test payload, continue to Webhook export for the customer-facing export action and Status sync and duplicate handling when the downstream provider task needs tracking. Use Authentication and headers for envelope rules, Request and response examples for placeholder JSON, and Errors, idempotency, retries and rate limits when 400, 401, 403, 422 or 429 responses need interpretation.

Was this page helpful?

Feedback goes into the product documentation review queue.