> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook endpoint > Registers a webhook endpoint for the project. The response includes a one-time `signingSecret` that the partner must store to verify incoming webhook signatures. `mode` defaults to `NOTIFICATION` (async event delivery), of which a maximum of 5 ACTIVE per project is enforced - disable an existing one to make room. Pass `REQUEST` to register the project's single synchronous authorization endpoint (exactly one per project, rotate-only). ## OpenAPI ````yaml /api-reference/openapi.json post /webhooks/ openapi: 3.1.0 info: title: Reap API version: 1.0.0 description: Reap platform API servers: - url: https://sandbox.api.reap.global description: Sandbox - url: https://prod.api.reap.global description: Production security: - bearerAuth: [] tags: - name: Accounts - name: Activities - name: Card Designs - name: Card Shipments - name: Card Transactions - name: Cards - name: Companies - name: Crypto Deposits - name: Policies - name: Simulation - name: Users - name: Virtual Asset Postings - name: Virtual Assets - name: Webhooks paths: /webhooks/: post: tags: - Webhooks summary: Create webhook endpoint description: >- Registers a webhook endpoint for the project. The response includes a one-time `signingSecret` that the partner must store to verify incoming webhook signatures. `mode` defaults to `NOTIFICATION` (async event delivery), of which a maximum of 5 ACTIVE per project is enforced - disable an existing one to make room. Pass `REQUEST` to register the project's single synchronous authorization endpoint (exactly one per project, rotate-only). operationId: create_webhooks parameters: - name: Reap-Version in: header required: true schema: type: string enum: - '2025-02-14' description: API version (YYYY-MM-DD) example: '2025-02-14' - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 255 description: >- Unique key for safely retrying this request. Up to 255 characters; we recommend a UUIDv4. The first request executes and its response is cached; subsequent requests with the same key replay the cached response (24h retention). requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: >- Human-readable label for this webhook (e.g. `prod-events`, `staging-mirror`). Surfaced in logs and the partner dashboard. url: type: string maxLength: 500 format: uri description: >- HTTPS endpoint that will receive webhook POST requests. Must be reachable from the public internet (HTTPS only, no private IPs). mode: default: NOTIFICATION description: >- Interaction pattern of the endpoint. Defaults to `NOTIFICATION`. type: string enum: - NOTIFICATION - REQUEST example: NOTIFICATION required: - name - url application/x-www-form-urlencoded: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: >- Human-readable label for this webhook (e.g. `prod-events`, `staging-mirror`). Surfaced in logs and the partner dashboard. url: type: string maxLength: 500 format: uri description: >- HTTPS endpoint that will receive webhook POST requests. Must be reachable from the public internet (HTTPS only, no private IPs). mode: default: NOTIFICATION description: >- Interaction pattern of the endpoint. Defaults to `NOTIFICATION`. type: string enum: - NOTIFICATION - REQUEST example: NOTIFICATION required: - name - url multipart/form-data: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: >- Human-readable label for this webhook (e.g. `prod-events`, `staging-mirror`). Surfaced in logs and the partner dashboard. url: type: string maxLength: 500 format: uri description: >- HTTPS endpoint that will receive webhook POST requests. Must be reachable from the public internet (HTTPS only, no private IPs). mode: default: NOTIFICATION description: >- Interaction pattern of the endpoint. Defaults to `NOTIFICATION`. type: string enum: - NOTIFICATION - REQUEST example: NOTIFICATION required: - name - url responses: '200': description: Created webhook, including its one-time signing secret. content: application/json: schema: type: object properties: id: type: string format: uuid description: Unique webhook identifier name: type: string description: Human-readable label url: type: string description: HTTPS endpoint that receives signed POSTs status: type: string enum: - ACTIVE - DISABLED description: Lifecycle status. Disabled webhooks receive no deliveries. example: ACTIVE mode: type: string enum: - NOTIFICATION - REQUEST description: Interaction pattern of the endpoint. example: NOTIFICATION lastUsedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' description: Timestamp of the most recent successful delivery createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 creation timestamp updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 last update timestamp signingSecret: type: string description: >- HMAC signing secret. Returned exactly once. Store it securely - it cannot be retrieved again. The previous secret (if any) is invalidated immediately. required: - id - name - url - status - mode - lastUsedAt - createdAt - updatedAt - signingSecret '400': description: >- Webhook URL is invalid - must be HTTPS and resolve to a public address content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: INVALID_WEBHOOK_URL message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: InvalidWebhookUrlError '409': description: Response for status 409 content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string const: WEBHOOK_LIMIT_EXCEEDED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: WebhookLimitExceededError description: Maximum number of active webhooks reached for this project - type: object properties: error: type: object properties: code: type: string const: REQUEST_WEBHOOK_ALREADY_EXISTS message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: RequestWebhookAlreadyExistsError description: >- The project already has a REQUEST-mode webhook. A REQUEST-mode endpoint is synchronous and rotate-only; update its URL or secret in place instead of registering another. components: securitySchemes: bearerAuth: type: http scheme: bearer description: API key as Bearer token ````