> ## Documentation Index > Fetch the complete documentation index at: https://docs.noresponse.org/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint > Registers an endpoint and returns it with its first signing secret. The secret is shown only in this answer: store it where your receiver reads it. The URL must be `https` on port 443 or 8443, name a host by DNS name, and resolve only to public addresses. It is checked now and on every delivery. You can hold 5 endpoints. A new endpoint is unverified and receives no assessment event until it echoes an `endpoint.verification` challenge. Send one with `POST /v1/webhooks/{endpoint_id}/test`. Requires the `webhooks` scope; `response_mode: "detailed"` also needs the `detailed` scope. Registration is not idempotent: a retry after a lost answer registers a second endpoint, which you can list and delete. ## OpenAPI ````yaml /openapi.json post /v1/webhooks openapi: 3.1.0 info: title: NoResponse API version: '1' description: >- The NoResponse API assesses a signup, login or purchase and answers with the account's one current risk: a 0 to 100 score, a decision for the flow (`allow`, `step_up`, `review` or `block`), the reasons behind it and the decision for each flow. The assessment's own facts, such as its status, confidence and incomplete sources, sit under `detail`. Authenticate every request with your API key as `Authorization: Bearer nrk_...`. Call the API only from your backend. Guides, SDKs and webhook verification are at [docs.noresponse.org](https://docs.noresponse.org/). Every error is an RFC 9457 problem document; see [Errors](https://docs.noresponse.org/reference/errors). servers: - url: https://api.noresponse.org description: Production security: - tenantBearer: [] tags: - name: assess x-displayName: Assessments x-group: Assessments description: Create, read and list assessments, and report outcomes. - name: accounts x-displayName: Accounts x-group: Accounts description: >- Each of your accounts holds one current risk, and its assessments are its history. - name: usage x-displayName: Key usage x-group: Key usage description: >- Report usage of the API keys your signup gate issued, so a shared or stolen key raises its account's risk. - name: keys x-displayName: API keys x-group: API keys description: Rotate your own API key. - name: integrations x-displayName: Integrations x-group: Integrations description: >- Hosted endpoints that answer your WorkOS or Auth0 sign-up and sign-in hooks. - name: webhooks x-displayName: Webhooks x-group: Webhooks description: Your webhook endpoints, and the signed events NoResponse sends to them. paths: /v1/webhooks: post: tags: - webhooks summary: Register a webhook endpoint description: >- Registers an endpoint and returns it with its first signing secret. The secret is shown only in this answer: store it where your receiver reads it. The URL must be `https` on port 443 or 8443, name a host by DNS name, and resolve only to public addresses. It is checked now and on every delivery. You can hold 5 endpoints. A new endpoint is unverified and receives no assessment event until it echoes an `endpoint.verification` challenge. Send one with `POST /v1/webhooks/{endpoint_id}/test`. Requires the `webhooks` scope; `response_mode: "detailed"` also needs the `detailed` scope. Registration is not idempotent: a retry after a lost answer registers a second endpoint, which you can list and delete. operationId: createWebhookEndpoint requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointRequest' examples: standard: value: url: https://hooks.example.com/noresponse detailed: value: url: https://hooks.example.com:8443/noresponse/detailed response_mode: detailed responses: '201': $ref: '#/components/responses/WebhookEndpointCreated' '400': $ref: '#/components/responses/InvalidWebhookEndpoint' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/WorkspaceForbidden' '409': $ref: '#/components/responses/WebhookEndpointLimitReached' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' security: - tenantBearer: [] x-codeSamples: - lang: curl label: cURL source: | curl --request POST \ --url 'https://api.noresponse.org/v1/webhooks' \ --header "Authorization: Bearer $NORESPONSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "url": "https://hooks.example.com/noresponse" }' - lang: typescript label: TypeScript source: | import { NoResponse } from "@noresponse/node"; const noResponse = new NoResponse({ apiKey: process.env["NORESPONSE_API_KEY"] ?? "", }); async function run() { const result = await noResponse.webhookEndpoints.create({ url: "https://hooks.example.com/noresponse", }); console.log(result); } run(); - lang: python label: Python source: | from noresponse import NoResponse import os with NoResponse( api_key=os.getenv("NORESPONSE_API_KEY", ""), ) as no_response: res = no_response.webhook_endpoints.create(url="https://hooks.example.com/noresponse") # Handle response print(res) - lang: go label: Go source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tnoresponse \"github.com/noresponsehq/go/v5\"\n\t\"github.com/noresponsehq/go/v5/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := noresponse.New(\n noresponse.WithSecurity(os.Getenv(\"NORESPONSE_API_KEY\")),\n )\n\n res, err := s.WebhookEndpoints.Create(ctx, components.WebhookEndpointRequest{\n URL: \"https://hooks.example.com/noresponse\",\n })\n if err != nil {\n log.Fatal(err)\n }\n if res != nil {\n // handle response\n }\n}\n" - lang: java label: Java source: > package hello.world; import java.lang.Exception; import org.noresponse.NoResponse; import org.noresponse.models.errors.AuthenticationException; import org.noresponse.models.errors.BadRequestException; import org.noresponse.models.errors.ConflictException; import org.noresponse.models.errors.NotFoundException; import org.noresponse.models.errors.PermissionDeniedException; import org.noresponse.models.errors.RateLimitException; import org.noresponse.models.operations.CreateWebhookEndpointResponse; import org.noresponse.models.shared.WebhookEndpointRequest; public class Application { public static void main(String[] args) throws Exception { NoResponse sdk = NoResponse.builder() .apiKey(System.getenv().getOrDefault("NORESPONSE_API_KEY", "")) .build(); WebhookEndpointRequest req = WebhookEndpointRequest.builder() .url("https://hooks.example.com/noresponse") .build(); CreateWebhookEndpointResponse res = sdk.webhookEndpoints().create() .request(req) .call(); if (res.webhookEndpointCreated().isPresent()) { System.out.println(res.webhookEndpointCreated().get()); } } } - lang: csharp label: C# source: > using NoResponse; using NoResponse.Models.Shared; using System; var sdk = new NoResponseClient(apiKey: Environment.GetEnvironmentVariable("NORESPONSE_API_KEY")); WebhookEndpointRequest req = new WebhookEndpointRequest() { Url = "https://hooks.example.com/noresponse", }; var res = await sdk.WebhookEndpoints.CreateAsync(req); // handle response - lang: php label: PHP source: | setSecurity( getenv('NORESPONSE_API_KEY') ?: '' ) ->build(); $request = new Shared\WebhookEndpointRequest( url: 'https://hooks.example.com/noresponse', ); $response = $sdk->webhookEndpoints->create( request: $request ); if ($response->webhookEndpointCreated !== null) { // handle response } - lang: ruby label: Ruby source: | require 'noresponse' Models = ::NoResponse::Models s = ::NoResponse::NoResponseClient.new( api_key: ENV.fetch('NORESPONSE_API_KEY', '') ) req = Models::Shared::WebhookEndpointRequest.new( url: 'https://hooks.example.com/noresponse' ) res = s.webhook_endpoints.create(request: req) unless res.nil? # handle response end components: schemas: WebhookEndpointRequest: title: Webhook endpoint registration description: >- POST /v1/webhooks body. The workspace is the API key that signs the request, so it is not a body member. The URL must be https on port 443 or 8443 with a DNS name, not an IP literal, and every address the name resolves to must be public. type: object additionalProperties: false required: - url properties: url: type: string minLength: 12 maxLength: 2048 pattern: ^https:// not: description: >- A line feed anywhere, refused with `not` beside every anchored pattern. pattern: \n description: >- Where deliveries are sent: an https URL on port 443 or 8443, with a DNS host and no userinfo or fragment, at most 2048 characters. response_mode: enum: - standard - detailed default: standard description: >- The view assessment.updated events carry: standard (the default) or detailed, which needs an API key with the detailed scope as well. WebhookEndpointCreated: title: Registered webhook endpoint description: >- The 201 answer of POST /v1/webhooks: the new endpoint, unverified, and its first signing secret, shown once. Store the secret where the receiver reads it, then send endpoint.verification with POST /v1/webhooks/{endpoint_id}/test. type: object additionalProperties: false required: - endpoint - signing_secret properties: endpoint: title: Webhook endpoint description: >- One of the workspace's registered webhook endpoints. Signing secrets are not part of it: a secret is shown once, when it is issued (POST /v1/webhooks and POST /v1/webhooks/{endpoint_id}/rotate). type: object additionalProperties: false required: - endpoint_id - url - state - response_mode - created_at - signing_keys properties: endpoint_id: type: string pattern: ^whe_[0-9A-HJKMNP-TV-Z]{26}$ not: description: >- A line feed anywhere, refused with `not` beside every anchored pattern. pattern: \n description: Opaque id of the endpoint registration. url: type: string minLength: 12 maxLength: 2048 description: The destination URL, as registered. state: enum: - unverified - verified - disabled description: >- unverified until the endpoint echoes an endpoint.verification challenge (send one with POST /v1/webhooks/{endpoint_id}/test); verified receives assessment.updated events; disabled after 72 hours of continuous delivery failure, and verified again by the same challenge. response_mode: enum: - standard - detailed description: >- The view assessment.updated events carry: the assessment as GET /v1/assessments/{assessment_id} returns it in this response mode. created_at: type: string format: date-time verified_at: type: string format: date-time description: >- When the endpoint last echoed a challenge. Absent until it first does. signing_keys: type: array minItems: 1 maxItems: 64 items: type: object additionalProperties: false required: - key_id - created_at description: One signing key, by id. The secret is not included. properties: key_id: type: string pattern: ^whk_[A-Za-z0-9]{8,64}$ description: >- The signing key id, sent as NR-Webhook-Key-Id on every delivery it signs. created_at: type: string format: date-time expires_at: type: string format: date-time description: >- Present on a key a rotation replaced: it stops verifying at this instant, 7 days after the rotation. Absent on the key that signs. description: >- The keys a receiver may see in NR-Webhook-Key-Id, oldest first. The last one signs every new delivery; an older one keeps verifying until its expires_at. $defs: endpoint_id: type: string pattern: ^whe_[0-9A-HJKMNP-TV-Z]{26}$ not: description: >- A line feed anywhere, refused with `not` beside every anchored pattern. pattern: \n description: Opaque id of the endpoint registration. key_id: type: string pattern: ^whk_[A-Za-z0-9]{8,64}$ description: >- The signing key id, sent as NR-Webhook-Key-Id on every delivery it signs. signing_key: type: object additionalProperties: false required: - key_id - created_at description: One signing key, by id. The secret is not included. properties: key_id: type: string pattern: ^whk_[A-Za-z0-9]{8,64}$ description: >- The signing key id, sent as NR-Webhook-Key-Id on every delivery it signs. created_at: type: string format: date-time expires_at: type: string format: date-time description: >- Present on a key a rotation replaced: it stops verifying at this instant, 7 days after the rotation. Absent on the key that signs. signing_secret: type: object additionalProperties: false required: - key_id - secret - created_at description: >- A newly issued signing key with its secret, shown only in this answer. A receiver verifies NR-Webhook-Signature with the secret's UTF-8 bytes as the HMAC-SHA256 key. properties: key_id: type: string pattern: ^whk_[A-Za-z0-9]{8,64}$ description: >- The signing key id, sent as NR-Webhook-Key-Id on every delivery it signs. secret: type: string pattern: ^[A-Za-z0-9_-]{43}$ description: >- The signing secret: 32 random bytes as 43 characters of unpadded base64url. It is not stored in readable form or returned again. created_at: type: string format: date-time signing_secret: type: object additionalProperties: false required: - key_id - secret - created_at description: >- A newly issued signing key with its secret, shown only in this answer. A receiver verifies NR-Webhook-Signature with the secret's UTF-8 bytes as the HMAC-SHA256 key. properties: key_id: type: string pattern: ^whk_[A-Za-z0-9]{8,64}$ description: >- The signing key id, sent as NR-Webhook-Key-Id on every delivery it signs. secret: type: string pattern: ^[A-Za-z0-9_-]{43}$ description: >- The signing secret: 32 random bytes as 43 characters of unpadded base64url. It is not stored in readable form or returned again. created_at: type: string format: date-time Problem: title: Problem details error description: >- RFC 9457 problem-details error body returned by every non-2xx API response, extended with a stable machine code and request id. type: object additionalProperties: false required: - type - title - status - detail - code - request_id properties: type: type: string format: uri-reference title: type: string status: type: integer minimum: 400 maximum: 599 detail: type: string instance: type: string format: uri-reference code: type: string request_id: type: string minLength: 1 invalid_params: type: array items: type: object additionalProperties: false required: - field - reason properties: field: type: string minLength: 1 reason: type: string minLength: 1 example: type: string minLength: 1 responses: WebhookEndpointCreated: description: The endpoint, unverified, and its first signing secret, shown once. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreated' examples: created: value: endpoint: endpoint_id: whe_01JA2ZD0E1F2G3H4J5K6M7N8P9 url: https://hooks.example.com/noresponse state: unverified response_mode: standard created_at: '2026-10-22T09:00:00.000Z' signing_keys: - key_id: whk_01JA2ZD1M2N3P4Q5R6S7T8V9W0 created_at: '2026-10-22T09:00:00.000Z' signing_secret: key_id: whk_01JA2ZD1M2N3P4Q5R6S7T8V9W0 secret: Zm9yLWRvY3Mtb25seS1ub3QtYS1yZWFsLXNlY3JldDA created_at: '2026-10-22T09:00:00.000Z' InvalidWebhookEndpoint: description: >- The body is not JSON or does not match the request schema (invalid_request), or the URL is not a permitted webhook destination (webhook_url_refused): not https, a port other than 443 or 8443, userinfo or a fragment, an IP literal, a host that does not resolve, or any resolved address that is not public. invalid_params names the offending fields, never their values. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 400 code: enum: - invalid_request - webhook_url_refused examples: url_refused: value: type: https://docs.noresponse.org/problems/webhook-url-refused title: Webhook URL refused status: 400 detail: The URL is not a permitted webhook destination. code: webhook_url_refused request_id: 0123456789abcdef0123456789abcdef Unauthorized: description: No API key, or one that is malformed, unknown, revoked or expired. headers: Cache-Control: schema: type: string const: no-store required: true WWW-Authenticate: schema: type: string const: Bearer realm="noresponse-assessments" required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 401 code: enum: - unauthorized WorkspaceForbidden: description: >- The API key is valid but may not use this operation: it lacks the operation's scope, or its workspace is not entitled or is suspended. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 403 code: enum: - workspace_forbidden examples: missingScope: value: type: https://docs.noresponse.org/problems/workspace-forbidden title: Forbidden status: 403 detail: The API key does not carry a scope this operation accepts. code: workspace_forbidden request_id: 0123456789abcdef0123456789abcdef WebhookEndpointLimitReached: description: The workspace already holds 5 webhook endpoints. Delete one first. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 409 code: enum: - webhook_endpoint_limit_reached examples: limit: value: type: >- https://docs.noresponse.org/problems/webhook-endpoint-limit-reached title: Webhook endpoint limit reached status: 409 detail: The tenant already has 5 webhook endpoints; delete one first. code: webhook_endpoint_limit_reached request_id: 0123456789abcdef0123456789abcdef PayloadTooLarge: description: The body exceeds 32768 bytes. Refused before parsing. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 413 code: enum: - payload_too_large UnsupportedMediaType: description: Content-Type is not application/json. headers: Cache-Control: schema: type: string const: no-store required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 415 code: enum: - unsupported_media_type RateLimited: description: >- The workspace's rate or concurrency limit is exhausted. Retry-After says when to retry; the provider applies its own fallback meanwhile. headers: Cache-Control: schema: type: string const: no-store required: true Retry-After: description: >- Whole seconds to wait before polling or retrying. Required on 202, 429 and 503. schema: type: string pattern: >- ^(?:[1-9]|[1-9][0-9]|[1-9][0-9]{2}|[12][0-9]{3}|3[0-5][0-9]{2}|3600)$ description: Whole decimal seconds; wait at least this long. required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 429 code: enum: - rate_limited examples: limited: value: type: https://docs.noresponse.org/problems/rate-limited title: Rate limited status: 429 detail: >- The tenant's assessment rate is exhausted; retry after the Retry-After interval. code: rate_limited request_id: 0123456789abcdef0123456789abcdef ServiceUnavailable: description: >- The assessment could not be admitted at all (overload, shutdown or a dependency down). An assessment that was admitted answers partial or pending instead of 503. headers: Cache-Control: schema: type: string const: no-store required: true Retry-After: description: >- Whole seconds to wait before polling or retrying. Required on 202, 429 and 503. schema: type: string pattern: >- ^(?:[1-9]|[1-9][0-9]|[1-9][0-9]{2}|[12][0-9]{3}|3[0-5][0-9]{2}|3600)$ description: Whole decimal seconds; wait at least this long. required: true X-Request-ID: description: The request correlation id, 32 lowercase hexadecimal characters. schema: type: string pattern: ^[0-9a-f]{32}$ not: pattern: \n required: true content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - properties: status: const: 503 code: enum: - service_unavailable securitySchemes: tenantBearer: type: http scheme: bearer description: >- Your API key, sent as `Authorization: Bearer `. A key is `nrk_live_` or `nrk_test_`, a 26-character key id, `_` and a 43-character secret. A key sees only its own environment's data. Each key has one or more scopes: `assess` creates and reads assessments, records outcomes and reports key usage; `history` reads assessments, an account's current risk and an account's history, and erases an account; `detailed` adds the detailed view; `webhooks` registers, tests, rotates and deletes webhook endpoints; `integrations` registers and manages hosted provider integrations. A missing, unknown, revoked or expired key answers 401. A valid key without the scope an operation needs answers 403. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.