diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 4d299878d..20140ebcb 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -11260,6 +11260,81 @@ webhooks: application/json: schema: $ref: '#/components/schemas/Error409' + wallet-operation: + post: + summary: Wallet operation completed or failed + description: | + Webhook that is called when an asynchronous embedded-wallet operation reaches a terminal state. Fires `WALLET_OPERATION.COMPLETED` on terminal success and `WALLET_OPERATION.FAILED` on terminal failure. + + The specific operation is carried in `data.operationType` (`auth_credential.delete`, `session.revoke`, or `wallet.export`). The webhook carries no sensitive result material — only the `operationId`, `operationType`, `status`, and (on failure) `error.code`. For a data-returning operation (`wallet.export`), the result is never delivered in the webhook; retrieve it by resubmitting the original signed export request until it returns the result. + + This endpoint should be implemented by clients of the Grid API. + + ### Authentication + + The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. + To verify the signature: + 1. Get the Grid public key provided to you during integration + 2. Decode the base64 signature from the header + 3. Create a SHA-256 hash of the request body + 4. Verify the signature using the public key and the hash + + If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. + operationId: walletOperationWebhook + tags: + - Webhooks + security: + - WebhookSignature: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WalletOperationWebhook' + examples: + completed: + summary: Wallet export completed + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000040 + type: WALLET_OPERATION.COMPLETED + timestamp: '2026-06-08T14:31:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: wallet.export + status: completed + failed: + summary: Session revoke failed terminally + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000041 + type: WALLET_OPERATION.FAILED + timestamp: '2026-06-08T14:32:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-00000000009a + operationType: session.revoke + status: failed + error: + code: DeleteApiKeysFailed + responses: + '200': + description: Webhook received successfully + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized - Signature validation failed + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '409': + description: Conflict - Webhook has already been processed (duplicate id) + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' components: securitySchemes: BasicAuth: @@ -24675,6 +24750,8 @@ components: - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED - TEST description: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. BaseWebhook: @@ -24916,6 +24993,60 @@ components: - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION + OperationError: + type: object + required: + - code + properties: + code: + type: string + description: Machine-readable failure code for a `FAILED` operation. + example: DeleteApiKeysFailed + WalletOperationWebhookData: + type: object + required: + - operationId + - operationType + - status + properties: + operationId: + type: string + description: The `Operation:` id of the operation that reached a terminal state. + example: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: + type: string + description: The kind of operation that reached a terminal state. + enum: + - auth_credential.delete + - session.revoke + - wallet.export + example: wallet.export + status: + type: string + description: Terminal status of the operation. + enum: + - completed + - failed + example: completed + error: + anyOf: + - $ref: '#/components/schemas/OperationError' + - type: 'null' + description: Present only on `failed`; `null` otherwise. + WalletOperationWebhook: + allOf: + - $ref: '#/components/schemas/BaseWebhook' + - type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/WalletOperationWebhookData' + type: + type: string + enum: + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED requestBodies: DocumentUploadRequestBody: required: true diff --git a/openapi.yaml b/openapi.yaml index 4d299878d..20140ebcb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -11260,6 +11260,81 @@ webhooks: application/json: schema: $ref: '#/components/schemas/Error409' + wallet-operation: + post: + summary: Wallet operation completed or failed + description: | + Webhook that is called when an asynchronous embedded-wallet operation reaches a terminal state. Fires `WALLET_OPERATION.COMPLETED` on terminal success and `WALLET_OPERATION.FAILED` on terminal failure. + + The specific operation is carried in `data.operationType` (`auth_credential.delete`, `session.revoke`, or `wallet.export`). The webhook carries no sensitive result material — only the `operationId`, `operationType`, `status`, and (on failure) `error.code`. For a data-returning operation (`wallet.export`), the result is never delivered in the webhook; retrieve it by resubmitting the original signed export request until it returns the result. + + This endpoint should be implemented by clients of the Grid API. + + ### Authentication + + The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. + To verify the signature: + 1. Get the Grid public key provided to you during integration + 2. Decode the base64 signature from the header + 3. Create a SHA-256 hash of the request body + 4. Verify the signature using the public key and the hash + + If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. + operationId: walletOperationWebhook + tags: + - Webhooks + security: + - WebhookSignature: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WalletOperationWebhook' + examples: + completed: + summary: Wallet export completed + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000040 + type: WALLET_OPERATION.COMPLETED + timestamp: '2026-06-08T14:31:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: wallet.export + status: completed + failed: + summary: Session revoke failed terminally + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000041 + type: WALLET_OPERATION.FAILED + timestamp: '2026-06-08T14:32:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-00000000009a + operationType: session.revoke + status: failed + error: + code: DeleteApiKeysFailed + responses: + '200': + description: Webhook received successfully + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized - Signature validation failed + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '409': + description: Conflict - Webhook has already been processed (duplicate id) + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' components: securitySchemes: BasicAuth: @@ -24675,6 +24750,8 @@ components: - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED - TEST description: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. BaseWebhook: @@ -24916,6 +24993,60 @@ components: - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION + OperationError: + type: object + required: + - code + properties: + code: + type: string + description: Machine-readable failure code for a `FAILED` operation. + example: DeleteApiKeysFailed + WalletOperationWebhookData: + type: object + required: + - operationId + - operationType + - status + properties: + operationId: + type: string + description: The `Operation:` id of the operation that reached a terminal state. + example: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: + type: string + description: The kind of operation that reached a terminal state. + enum: + - auth_credential.delete + - session.revoke + - wallet.export + example: wallet.export + status: + type: string + description: Terminal status of the operation. + enum: + - completed + - failed + example: completed + error: + anyOf: + - $ref: '#/components/schemas/OperationError' + - type: 'null' + description: Present only on `failed`; `null` otherwise. + WalletOperationWebhook: + allOf: + - $ref: '#/components/schemas/BaseWebhook' + - type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/WalletOperationWebhookData' + type: + type: string + enum: + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED requestBodies: DocumentUploadRequestBody: required: true diff --git a/openapi/components/schemas/webhooks/OperationError.yaml b/openapi/components/schemas/webhooks/OperationError.yaml new file mode 100644 index 000000000..7a4533345 --- /dev/null +++ b/openapi/components/schemas/webhooks/OperationError.yaml @@ -0,0 +1,8 @@ +type: object +required: + - code +properties: + code: + type: string + description: Machine-readable failure code for a `FAILED` operation. + example: DeleteApiKeysFailed diff --git a/openapi/components/schemas/webhooks/WalletOperationWebhook.yaml b/openapi/components/schemas/webhooks/WalletOperationWebhook.yaml new file mode 100644 index 000000000..a7dd45d8f --- /dev/null +++ b/openapi/components/schemas/webhooks/WalletOperationWebhook.yaml @@ -0,0 +1,13 @@ +allOf: + - $ref: ./BaseWebhook.yaml + - type: object + required: + - data + properties: + data: + $ref: ./WalletOperationWebhookData.yaml + type: + type: string + enum: + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED diff --git a/openapi/components/schemas/webhooks/WalletOperationWebhookData.yaml b/openapi/components/schemas/webhooks/WalletOperationWebhookData.yaml new file mode 100644 index 000000000..b90638e6f --- /dev/null +++ b/openapi/components/schemas/webhooks/WalletOperationWebhookData.yaml @@ -0,0 +1,30 @@ +type: object +required: + - operationId + - operationType + - status +properties: + operationId: + type: string + description: The `Operation:` id of the operation that reached a terminal state. + example: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: + type: string + description: The kind of operation that reached a terminal state. + enum: + - auth_credential.delete + - session.revoke + - wallet.export + example: wallet.export + status: + type: string + description: Terminal status of the operation. + enum: + - completed + - failed + example: completed + error: + anyOf: + - $ref: ./OperationError.yaml + - type: 'null' + description: Present only on `failed`; `null` otherwise. diff --git a/openapi/components/schemas/webhooks/WebhookType.yaml b/openapi/components/schemas/webhooks/WebhookType.yaml index fab72c524..e78db694d 100644 --- a/openapi/components/schemas/webhooks/WebhookType.yaml +++ b/openapi/components/schemas/webhooks/WebhookType.yaml @@ -39,6 +39,8 @@ enum: - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION + - WALLET_OPERATION.COMPLETED + - WALLET_OPERATION.FAILED - TEST description: >- Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index b6143351f..9b0949716 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -397,6 +397,8 @@ webhooks: $ref: webhooks/card-funding-source-change.yaml card-transaction: $ref: webhooks/card-transaction.yaml + wallet-operation: + $ref: webhooks/wallet-operation.yaml security: - BasicAuth: [] - AgentAuth: [] diff --git a/openapi/webhooks/wallet-operation.yaml b/openapi/webhooks/wallet-operation.yaml new file mode 100644 index 000000000..720f8bff3 --- /dev/null +++ b/openapi/webhooks/wallet-operation.yaml @@ -0,0 +1,94 @@ +post: + summary: Wallet operation completed or failed + description: > + Webhook that is called when an asynchronous embedded-wallet operation + reaches a terminal state. Fires `WALLET_OPERATION.COMPLETED` on terminal + success and `WALLET_OPERATION.FAILED` on terminal failure. + + + The specific operation is carried in `data.operationType` + (`auth_credential.delete`, `session.revoke`, or `wallet.export`). The webhook + carries no sensitive result material — only the `operationId`, + `operationType`, `status`, and (on failure) `error.code`. For a + data-returning operation (`wallet.export`), the result is never delivered in + the webhook; retrieve it by resubmitting the original signed export request + until it returns the result. + + + This endpoint should be implemented by clients of the Grid API. + + + ### Authentication + + + The webhook includes a signature in the `X-Grid-Signature` header that + allows you to verify that the webhook was sent by Grid. + + To verify the signature: + + 1. Get the Grid public key provided to you during integration + + 2. Decode the base64 signature from the header + + 3. Create a SHA-256 hash of the request body + + 4. Verify the signature using the public key and the hash + + + If the signature verification succeeds, the webhook is authentic. If not, it + should be rejected. + operationId: walletOperationWebhook + tags: + - Webhooks + security: + - WebhookSignature: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '../components/schemas/webhooks/WalletOperationWebhook.yaml' + examples: + completed: + summary: Wallet export completed + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000040 + type: WALLET_OPERATION.COMPLETED + timestamp: '2026-06-08T14:31:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-000000000099 + operationType: wallet.export + status: completed + failed: + summary: Session revoke failed terminally + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000041 + type: WALLET_OPERATION.FAILED + timestamp: '2026-06-08T14:32:00Z' + data: + operationId: Operation:019542f5-b3e7-1d02-0000-00000000009a + operationType: session.revoke + status: failed + error: + code: DeleteApiKeysFailed + responses: + '200': + description: Webhook received successfully + '400': + description: Bad request + content: + application/json: + schema: + $ref: ../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized - Signature validation failed + content: + application/json: + schema: + $ref: ../components/schemas/errors/Error401.yaml + '409': + description: Conflict - Webhook has already been processed (duplicate id) + content: + application/json: + schema: + $ref: ../components/schemas/errors/Error409.yaml