> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook > Registers a new webhook destination for the specified account. The response carries the signing secret in plaintext. Partners must store it and use it to verify the signature on inbound webhook deliveries. The secret is shown only here at creation time; if it is later lost or compromised, mint a replacement with RotateWebhookSecret (which returns the new secret, also only once). ## OpenAPI ````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/webhooks openapi: 3.1.0 info: title: PWS Public API version: '1' description: >- Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications. contact: name: Payward Services servers: - url: https://api.sandbox.services.payward.com security: [] tags: - name: Assets description: List the assets PWS is willing to swap. x-displayName: Assets - name: Conversions description: >- Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits. x-displayName: Conversions - name: Auto Earn description: >- Manage Auto Earn preferences and retrieve allocation and reward information. x-displayName: Auto Earn - name: Bonded Earn description: >- Allocate funds to and deallocate funds from bonded earn strategies, review allocations, and track request status. x-displayName: Bonded Earn - name: Funding description: >- Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts. x-displayName: Funding - name: Derivative transfers description: >- Move funds between an account's spot balance and the same owner's futures balance. x-displayName: Derivative transfers - name: Portfolio description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' x-displayName: Portfolio - name: Ramp description: >- Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences. x-displayName: Ramp - name: Reports description: Settlement and reconciliation reports for the partner. x-displayName: Reports - name: Swaps description: Account-funded quotes that lock a price until they expire or are executed. x-displayName: Swaps - name: Onchain quotes description: Wallet-funded quotes that return the data needed to settle onchain. x-displayName: Onchain quotes - name: Price trigger swaps description: Swaps that wait for a target price before submitting a trade. x-displayName: Price trigger swaps - name: Travel Rule verifications description: Travel Rule address ownership verification flows. x-displayName: Travel Rule verifications - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions an account-owned user from an external reference and optional email. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. x-displayName: Users - name: Verifications description: Identity verification (KYC) submission and status for end users. x-displayName: Verifications - name: Webhooks description: >- Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures. x-displayName: Webhooks paths: /v1/webhooks: post: tags: - Webhooks summary: Create webhook description: >- Registers a new webhook destination for the specified account. The response carries the signing secret in plaintext. Partners must store it and use it to verify the signature on inbound webhook deliveries. The secret is shown only here at creation time; if it is later lost or compromised, mint a replacement with RotateWebhookSecret (which returns the new secret, also only once). operationId: createWebhook requestBody: content: application/json: schema: description: >- Request to register a new webhook destination. The owning tenant is derived from the authenticated caller. There is no account identifier in the request. type: object properties: url: description: >- HTTPS destination URL. Must be reachable from the webhooks service and serve a valid TLS certificate. type: string minLength: 8 maxLength: 2048 description: description: >- Optional free-form label, shown in the operator portal. Max 500 chars. type: string maxLength: 500 events: description: >- Events the webhook should be subscribed to. Required and must be non-empty: partners must opt in explicitly to avoid silent fan-out when new event types are added. type: array minItems: 1 maxItems: 100 uniqueItems: true items: $ref: '#/components/schemas/Webhooks_WebhookEventType' disabled: description: >- Create the webhook in a disabled state. Omit (or pass false) to start delivering immediately; pass true to register the endpoint without delivering any events until it is re-enabled via UpdateWebhook. type: boolean required: - url - events examples: create-webhook-request: summary: Create webhook request value: url: https://partner.example.com/hooks/quote description: primary delivery events: - quote.executed - quote.cancelled required: true responses: '201': description: Successful response headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: description: >- Response from CreateWebhook. The signing secret is returned in plaintext exactly once. Partners must persist it before discarding the response; it cannot be re-read later. type: object properties: data: description: >- Data envelope returned exactly once after a successful CreateWebhook. Mirrors the webhook representation field-for-field and adds the one-time signing secret as a peer field. type: object properties: id: description: >- Stable identifier assigned at creation time. Use this in subsequent Get/Update/Delete calls. type: string url: description: >- HTTPS destination URL that the webhook payload will be POSTed to. type: string description: description: >- Free-form partner-supplied label. Empty when no description was set. type: string disabled: description: >- When true, the webhook is registered but no events are being delivered. Flip to false via UpdateWebhook to resume deliveries. type: boolean created_at: $ref: '#/components/schemas/DateTime' description: Time at which the webhook was created. updated_at: $ref: '#/components/schemas/DateTime' description: Time at which the webhook was last updated. signing_secret: description: >- HMAC-SHA256 signing secret. Partners use this to verify the signature header on every inbound webhook delivery. type: string format: password events: description: >- Events the webhook is subscribed to. Mirrors the request's `events` field after server-side normalization. type: array maxItems: 100 uniqueItems: true items: $ref: '#/components/schemas/Webhooks_WebhookEventType' required: - id - url - description - disabled - signing_secret - events required: - data examples: create-webhook-response: summary: Create webhook response value: data: id: ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5 url: https://partner.example.com/hooks/quote description: primary delivery disabled: false created_at: '2026-05-25T11:30:00Z' updated_at: '2026-05-25T11:30:00Z' signing_secret: whsec_7nM1q4bV2jKbMZhYa3sAehO9W8r7QZD2 events: - quote.executed - quote.cancelled '400': $ref: '#/components/responses/WebhooksBadRequestResponse' '401': $ref: '#/components/responses/WebhooksUnauthenticatedResponse' '403': $ref: '#/components/responses/WebhooksForbiddenResponse' '429': $ref: '#/components/responses/WebhooksResourceExhaustedResponse' '500': $ref: '#/components/responses/WebhooksInternalResponse' '503': $ref: '#/components/responses/WebhooksUnavailableResponse' '504': $ref: '#/components/responses/WebhooksDeadlineExceededResponse' security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: schemas: Webhooks_WebhookEventType: title: WebhookEventType description: Event type supported by the webhooks API. type: string enum: - quote.executed - quote.cancelled - quote.execution_failed - user.closed - user.disabled - conversion.deposit_completed - conversion.deposit_failed - conversion.deposit_held - conversion.withdrawal_completed - conversion.withdrawal_failed - conversion.quote_execution_failed - conversion.travel_rule_blocked - transaction.swap - transaction.price_trigger_swap - transaction.earn_reward - transaction.deposit - transaction.withdrawal - transaction.transfer - conversion.quote_executed - funds.deposit_received - funds.deposit_held - funds.deposit_credited - funds.deposit_returned - funds.deposit_failed - verification.requirements_updated - verification.updated - price_trigger_swap.executed - price_trigger_swap.execution_failed - price_trigger_swap.cancelled - price_trigger_swap.created - price_trigger_swap.failed - funds.withdrawal_held - funds.withdrawal_complete - funds.withdrawal_failed - recurring_swap.created - recurring_swap.executed - recurring_swap.execution_failed - recurring_swap.cancelled - recurring_swap.failed - recurring_swap.paused - recurring_swap.resumed - transaction.recurring_swap DateTime: description: RFC 3339 timestamp. type: string format: date-time BadRequestError: title: Bad Request description: Request validation failed or the request could not be processed. oneOf: - title: Bad Request allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 const: 400 code: type: string enum: - bad_request - title: Gateway description: >- Gateway-level validation failure returned before the request reaches the service. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 400 code: type: string const: gateway UnauthenticatedError: title: Unauthenticated description: Authentication credentials are missing, invalid, or not accepted. oneOf: - title: Unauthenticated allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 401 code: type: string enum: - unauthenticated - title: Gateway description: Authentication failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 401 code: type: string const: gateway ForbiddenError: title: Forbidden description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 403 code: type: string enum: - forbidden - title: Gateway description: Authorization failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 500 code: type: string enum: - internal UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 503 code: type: string enum: - unavailable DeadlineExceededError: description: The request deadline was exceeded before a response could be produced. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 504 code: type: string enum: - deadline_exceeded PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: Enforces HTTPS for the duration specified by `max-age`. schema: type: string example: max-age=31536000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store responses: WebhooksBadRequestResponse: description: Validation error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/BadRequestError' examples: invalid-request: $ref: '#/components/examples/webhooks-bad-request' WebhooksUnauthenticatedResponse: description: Authentication failed headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: $ref: '#/components/examples/webhooks-unauthenticated' WebhooksForbiddenResponse: description: Permission denied headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: caller-is-not-allowed: $ref: '#/components/examples/webhooks-forbidden' WebhooksResourceExhaustedResponse: description: Rate limit exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: $ref: '#/components/examples/webhooks-resource-exhausted' WebhooksInternalResponse: description: Internal server error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: $ref: '#/components/examples/webhooks-internal' WebhooksUnavailableResponse: description: Service unavailable headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: $ref: '#/components/examples/webhooks-service-unavailable' WebhooksDeadlineExceededResponse: description: Deadline exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: $ref: '#/components/examples/webhooks-deadline-exceeded' examples: webhooks-bad-request: summary: Invalid request value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 400 code: bad_request causes: - field: page_size message: must be between 1 and 25 webhooks-unauthenticated: summary: Authentication failed value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 401 code: unauthenticated webhooks-forbidden: summary: Caller is not allowed value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 403 code: forbidden webhooks-resource-exhausted: summary: Rate limit exceeded value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 429 code: resource_exhausted webhooks-internal: summary: Internal error value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 500 code: internal webhooks-service-unavailable: summary: Service unavailable value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 503 code: unavailable webhooks-deadline-exceeded: summary: Request deadline exceeded value: error: type: webhooks_error instance: req_01H00000000000000000000000 status: 504 code: deadline_exceeded securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey in: header name: API-Sign description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey in: header name: API-Nonce description: Monotonically increasing nonce included in the request signature. ````