> ## Documentation Index > Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook subscription > Subscribes a URL to one v2 event. The response includes the signing `secret`. We return it only here, so store it. See [Verifying Webhooks](/guides/verifying-webhooks). In production the URL must use `https`. ## OpenAPI ````yaml openapi-v2.json POST /webhook_subscription openapi: 3.1.0 info: title: Etherfuse FX API description: >- Partner-facing ramp API, version 2: payment accounts, quotes, orders and webhooks. license: name: Proprietary version: 2.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Payment Accounts description: >- Register the bank accounts and wallets that money moves from and to, and read their readiness per rail. - name: Quotes description: Price a transfer between two registered payment accounts. - name: Orders description: Create orders from quotes and track them. - name: Webhook Subscriptions description: Subscribe to webhook events. - name: Webhook Events description: Payloads Etherfuse sends to your webhook subscriptions. - name: Sandbox description: Endpoints that work only in sandbox, for testing. - name: Assets description: The markets and tokens a quote can use, and the balances of a wallet. - name: Authentication description: >- Partner JWT authentication: exchange a JWT for an access token, or launch a user into the app. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: KYB description: Check where a business organization's KYB stands. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Organizations description: >- Your organization, your default partner fee, and the customer organizations you create. - name: Members description: >- The people who belong to a customer business organization and complete its KYB. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. paths: /webhook_subscription: post: tags: - Webhook Subscriptions summary: Create webhook subscription description: >- Subscribes a URL to one v2 event. The response includes the signing `secret`. We return it only here, so store it. See [Verifying Webhooks](/guides/verifying-webhooks). In production the URL must use `https`. operationId: v2CreateWebhookSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookSubscriptionRequest' example: url: https://example.com/etherfuse/webhooks eventType: orderUpdated responses: '201': description: The created subscription, with its secret. content: application/json: schema: $ref: '#/components/schemas/CreatedWebhookSubscription' '400': description: >- `invalid-request`: the body is malformed, has an unknown `eventType`, the `url` is not a valid URL, or it does not use `https` in production. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '409': description: '`conflict`: a subscription for this URL and event already exists.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '413': $ref: '#/components/responses/PayloadTooLarge' '500': $ref: '#/components/responses/InternalError' components: schemas: CreateWebhookSubscriptionRequest: type: object required: - url - eventType properties: url: type: string format: uri description: Where we send the event. Must use `https` in production. eventType: $ref: '#/components/schemas/WebhookEventType' CreatedWebhookSubscription: type: object required: - id - eventType - url - createdAt - updatedAt - secret properties: id: type: string format: uuid eventType: $ref: '#/components/schemas/WebhookEventType' url: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time secret: type: string description: >- HMAC key for verifying deliveries, encoded as URL-safe base64 with padding. Returned only in this response. Problem: type: object description: >- RFC 9457 problem details. Every v2 error uses this body with content type `application/problem+json`. `errors` is present only on `validation-error`. `required` and `missing` are present only on `registration-info-required`. required: - type - title - status - detail - instance properties: type: type: string format: uri description: >- `https://docs.etherfuse.com/ramp/v2/errors/` followed by the problem slug, for example `https://docs.etherfuse.com/ramp/v2/errors/quote-expired`. Switch on this value. example: https://docs.etherfuse.com/ramp/v2/errors/quote-expired title: type: string description: Short summary of the problem type. example: Quote expired status: type: integer description: The HTTP status code. example: 400 detail: type: string description: Human-readable explanation of this occurrence. Do not parse it. example: >- quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist instance: type: string description: Unique identifier for this occurrence. Quote it to support. example: >- tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d errors: type: array description: Present on `validation-error`. One entry per invalid field. items: $ref: '#/components/schemas/FieldViolation' required: type: array description: >- Present on `registration-info-required`. Every registration field the route requires, as JSON Pointers into the request, for example `#/registrationInfo/taxId`. items: type: string missing: type: array description: >- Present on `registration-info-required`. The required fields you must still send, as JSON Pointers into the request. items: type: string WebhookEventType: type: string enum: - orderUpdated - paymentAccountUpdated - kycUpdated - kybUpdated FieldViolation: type: object required: - pointer - detail properties: pointer: type: string description: >- JSON Pointer to the field in the request, for example `#/accountDetails/clabe`. example: '#/accountDetails/clabe' detail: type: string description: What is wrong with the field. example: This field is required. responses: Unauthorized: description: >- `unauthorized`: the `Authorization` header is missing, not ASCII, or does not hold a valid API key. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' PayloadTooLarge: description: '`payload-too-large`: the request body is too large.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' InternalError: description: >- `internal-error`: an unexpected error on our side. Retry with backoff, and quote `instance` to support if it persists. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header, with no `Bearer` prefix. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.