> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint > Register a new webhook endpoint. HIFI delivers event notifications to the endpoint's `url` for every event type listed in `subscriptions`. A signing secret is generated on creation and returned **once** in the `signingSecret` field of this response only. Use it to verify the signature of incoming webhook deliveries. It is not returned by any other endpoint, so store it securely. A profile may have at most 16 active webhook endpoints. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/webhook-endpoints openapi: 3.0.0 info: title: Hifi API version: 3.0.0 description: API documentation for HIFI servers: - url: https://production.hifi.com description: Production server - url: https://sandbox.hifi.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Counter Party description: Counter party endpoints - name: Crypto Transfer description: Crypto transfer and batch transfer endpoints - name: Wallet description: Wallet and wallet offer endpoints - name: External Account description: External bank account endpoints (under a counter party) - name: External Wallet description: External wallet endpoints (under a counter party) - name: External Card description: External card endpoints (under a counter party) - name: Token Swap description: Token swap endpoints - name: Bridge description: Bridge endpoints - name: Virtual Account description: Virtual account endpoints - name: Compliance description: Compliance and compliance link endpoints - name: Webhook Endpoint description: Webhook endpoint endpoints - name: File description: File upload endpoints - name: Onramp description: Onramp (fiat to crypto) endpoints - name: Offramp description: Offramp (crypto to fiat) endpoints - name: Orchestration Address description: Orchestration (liquidation) address endpoints - name: KYC Link description: Hosted and custom KYC/KYB link endpoints - name: Transfer Approval description: Transfer approval endpoints - name: Corridor description: Supported fiat/crypto transfer corridor endpoints - name: Migration description: v2-to-v3 ID mapping endpoints paths: /v3/webhook-endpoints: post: tags: - Webhook Endpoint summary: Create a webhook endpoint description: > Register a new webhook endpoint. HIFI delivers event notifications to the endpoint's `url` for every event type listed in `subscriptions`. A signing secret is generated on creation and returned **once** in the `signingSecret` field of this response only. Use it to verify the signature of incoming webhook deliveries. It is not returned by any other endpoint, so store it securely. A profile may have at most 16 active webhook endpoints. operationId: v3CreateWebhookEndpoint requestBody: $ref: '#/components/requestBodies/CreateWebhookEndpointBody' responses: '200': $ref: '#/components/responses/CreateWebhookEndpointResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: CreateWebhookEndpointBody: required: true description: Webhook endpoint details. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreate' example: name: Production events url: https://api.example.com/webhooks/hifi description: Receives all production event notifications subscriptions: - USER_CREATED - KYC_APPROVED - OFFRAMP_UPDATED responses: CreateWebhookEndpointResponse: description: >- Webhook endpoint created successfully. The `signingSecret` is returned only here. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreateObject' example: id: we_4mNpXwZ7bV1aLcs3Kf9dQ name: Production events url: https://api.example.com/webhooks/hifi description: Receives all production event notifications subscriptions: - USER_CREATED - KYC_APPROVED - OFFRAMP_UPDATED status: ACTIVE createdAt: '2026-07-01T10:30:00.000Z' updatedAt: '2026-07-01T10:30:00.000Z' signingSecret: whsec_9aB0xY4mNpXwZ7bV1aLdt3Kf9dQ2mNpXwZ7bV1aLcs BadRequestResponse: description: Bad Request — the request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: VALIDATION_ERROR message: One or more fields are invalid or missing. fields: - code: invalid_value message: Must be a valid email address field: email UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' ConflictResponse: description: >- Conflict — the request collides with the current state of the resource (e.g. idempotency-key reuse with a different payload). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: RESOURCE_CONFLICT message: Resource already exists or conflicts with current state InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: WebhookEndpointCreate: type: object description: Fields for creating a webhook endpoint. required: - name - url properties: name: type: string description: Human-readable name for the endpoint. example: Production events url: type: string format: uri description: HTTPS URL that event notifications are delivered to. example: https://api.example.com/webhooks/hifi description: type: string description: Optional description of the endpoint. example: Receives all production event notifications subscriptions: type: array description: Event types this endpoint subscribes to. items: $ref: '#/components/schemas/WebhookEndpointEventType' example: - USER_CREATED - OFFRAMP_UPDATED WebhookEndpointCreateObject: type: object description: | A newly created webhook endpoint. Includes the `signingSecret`, which is returned only in this response and cannot be retrieved again. allOf: - $ref: '#/components/schemas/WebhookEndpointObject' - type: object properties: signingSecret: type: string description: >- Secret used to verify the signature of incoming deliveries. Returned only on creation. example: whsec_9aB0xY4mNpXwZ7bV1aLdt3Kf9dQ2mNpXwZ7bV1aLcs ApiError: type: object description: >- Standard v3 error shape, returned by validation failures and business-logic errors alike. properties: type: type: string description: >- Machine-readable error type, e.g. VALIDATION_ERROR, ACTION_NOT_ALLOWED, RESOURCE_CONFLICT. example: VALIDATION_ERROR message: type: string description: Human-readable error message. example: One or more fields are invalid or missing. fields: type: array description: >- Present on field-level validation errors. One entry per problem field. items: type: object properties: code: type: string description: Error code related to the field issue. message: type: string description: Error message for the specific issue. field: type: string description: The name of the field that has an issue. Unauthorized: type: object properties: type: type: string description: Unauthorized enum example: UNAUTHORIZED message: type: string description: Unauthorized message example: Authentication required InternalServerError: type: object properties: type: type: string example: INTERNAL_SERVER_ERROR description: Internal server error enum message: type: string example: An internal server error occurred description: Internal server error message WebhookEndpointEventType: type: string description: A webhook event type that an endpoint can subscribe to. enum: - USER_CREATED - KYC_SUBMITTED - KYC_UNDER_REVIEW - KYC_RFI - KYC_APPROVED - KYC_REJECTED - ACCOUNT_ACTIVE - ACCOUNT_INACTIVE - VIRTUAL_ACCOUNT_CREATED - VIRTUAL_ACCOUNT_UPDATED - ONRAMP_CREATED - ONRAMP_UPDATE - OFFRAMP_CREATED - OFFRAMP_UPDATED example: USER_CREATED WebhookEndpointObject: type: object description: A webhook endpoint. properties: id: type: string description: Public ID of the webhook endpoint (prefixed with `we_`). example: we_4mNpXwZ7bV1aLcs3Kf9dQ name: type: string example: Production events url: type: string format: uri example: https://api.example.com/webhooks/hifi description: type: string example: Receives all production event notifications subscriptions: type: array description: Event types this endpoint is subscribed to. items: $ref: '#/components/schemas/WebhookEndpointEventType' example: - USER_CREATED - OFFRAMP_UPDATED status: type: string enum: - ACTIVE - PAUSED - DISABLED example: ACTIVE createdAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' updatedAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````