Lightspark Webhooks API
Webhook endpoints and configuration for receiving notifications
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lightspark-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Grid Webhooks API
description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.
'
version: '2025-10-13'
contact:
name: Lightspark Support
email: support@lightspark.com
license:
name: Proprietary
url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: Webhooks
description: Webhook endpoints and configuration for receiving notifications
paths: {}
webhooks:
agent-action:
post:
summary: Agent action pending approval webhook
description: 'Fired when an agent submits an action that requires platform approval before Grid will execute it. Use this to send a push notification to the customer so they can review and approve or reject the action in your app.
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.
The payload contains the full `AgentAction` — including the embedded quote or transfer details — so you can render the approval UI without a second API call. Approve or reject via `POST /agents/{agentId}/actions/{actionId}/approve` or `POST /agents/{agentId}/actions/{actionId}/reject`.
'
operationId: agentActionWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentActionWebhook'
examples:
pendingApproval:
summary: Agent action pending approval
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000020
type: AGENT_ACTION.PENDING_APPROVAL
timestamp: '2025-10-03T15:00:00Z'
data:
id: AgentAction:019542f5-b3e7-1d02-0000-000000000099
agentId: Agent:019542f5-b3e7-1d02-0000-000000000042
customerId: Customer:019542f5-b3e7-1d02-0000-000000000010
platformCustomerId: user-a1b2c3
status: PENDING_APPROVAL
type: EXECUTE_QUOTE
quote:
id: Quote:019542f5-b3e7-1d02-0000-000000000006
status: PENDING
expiresAt: '2025-10-03T15:00:30Z'
createdAt: '2025-10-03T15:00:00Z'
source:
sourceType: ACCOUNT
accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
destination:
destinationType: ACCOUNT
accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
sendingCurrency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
receivingCurrency:
code: INR
name: Indian Rupee
symbol: ₹
decimals: 2
totalSendingAmount: 50000
totalReceivingAmount: 4625000
exchangeRate: 92.5
feesIncluded: 250
transactionId: Transaction:019542f5-b3e7-1d02-0000-000000000099
createdAt: '2025-10-03T15:00:00Z'
updatedAt: '2025-10-03T15:00:00Z'
responses:
'200':
description: Webhook received and acknowledged.
'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'
incoming-payment:
post:
summary: Incoming payment webhook and approval mechanism
description: 'Webhook that is called when an incoming payment is received by a customer''s UMA address.
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.
### Payment Approval Flow
When a transaction has `status: "PENDING"`, this webhook serves as an approval mechanism:
1. The client should check the `counterpartyInformation` against their requirements
2. To APPROVE the payment synchronously, return a 200 OK response
3. To REJECT the payment, return a 403 Forbidden response with an Error object
4. To request more information, return a 422 Unprocessable Entity with specific missing fields
5. To process the payment asynchronously, return a 202 Accepted response and then call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint within 5 seconds. Note that synchronous approval/rejection is preferred where possible.
The Grid system will proceed or cancel the payment based on your response.
For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational.
'
operationId: incomingPaymentWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IncomingPaymentWebhook'
examples:
pendingPayment:
summary: Pending payment example requiring approval
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000007
type: INCOMING_PAYMENT.PENDING
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000005
status: PENDING
type: INCOMING
direction: CREDIT
destination:
destinationType: UMA_ADDRESS
umaAddress: $recipient@uma.domain
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
senderUmaAddress: $sender@external.domain
receiverUmaAddress: $recipient@uma.domain
receivedAmount:
amount: 50000
currency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
counterpartyInformation:
FULL_NAME: John Sender
BIRTH_DATE: '1985-06-15'
NATIONALITY: US
reconciliationInstructions:
reference: REF-123456789
requestedReceiverCustomerInfoFields:
- name: NATIONALITY
mandatory: true
- name: POSTAL_ADDRESS
mandatory: false
incomingCompletedPayment:
summary: Completed payment notification
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000007
type: INCOMING_PAYMENT.COMPLETED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000005
status: COMPLETED
type: INCOMING
direction: CREDIT
destination:
destinationType: UMA_ADDRESS
umaAddress: $recipient@uma.domain
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
senderUmaAddress: $sender@external.domain
receiverUmaAddress: $recipient@uma.domain
receivedAmount:
amount: 50000
currency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
settledAt: '2025-08-15T14:30:00Z'
createdAt: '2025-08-15T14:25:18Z'
description: Payment for services
reconciliationInstructions:
reference: REF-123456789
incomingCompletedCryptoPayment:
summary: Completed payment funded from an external crypto wallet
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000009
type: INCOMING_PAYMENT.COMPLETED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000006
status: COMPLETED
type: INCOMING
direction: CREDIT
source:
sourceType: REALTIME_FUNDING
currency: USDC
onChainTransaction:
transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf
network: SOLANA
destination:
destinationType: ACCOUNT
accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
receivedAmount:
amount: 100000
currency:
code: USDC
name: USD Coin
symbol: ''
decimals: 6
settledAt: '2025-08-15T14:30:00Z'
createdAt: '2025-08-15T14:25:18Z'
description: USDC deposit from self-custody wallet
responses:
'200':
description: 'Webhook received successfully.
For PENDING transactions, this indicates approval to proceed with the payment.
If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverCustomerInfo` object.
'
content:
application/json:
schema:
$ref: '#/components/schemas/IncomingPaymentWebhookResponse'
'202':
description: 'Webhook received and will be processed asynchronously. The synchronous 200 response should be preferred where possible. This asycnhronous path should only be used in
cases where the platform''s architecture requires async (but still very quick) processing before approving or rejecting the payment.
The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected.
'
'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'
'403':
description: 'Forbidden - Payment rejected by the client.
Only applicable for PENDING transactions.
'
content:
application/json:
schema:
$ref: '#/components/schemas/IncomingPaymentWebhookForbiddenResponse'
'409':
description: Conflict - Webhook has already been processed (duplicate id)
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'422':
description: 'Unprocessable Entity - Additional counterparty information required.
Only applicable for PENDING transactions.
'
content:
application/json:
schema:
$ref: '#/components/schemas/IncomingPaymentWebhookUnprocessableResponse'
outgoing-payment:
post:
summary: Outgoing payment status webhook
description: 'Webhook that is called when an outgoing payment''s status changes.
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.
This webhook is informational only and is sent when an outgoing payment completes successfully, fails, or is refunded.
'
operationId: outgoingPaymentWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OutgoingPaymentWebhook'
examples:
outgoingCompletedPayment:
summary: Completed outgoing payment
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000007
type: OUTGOING_PAYMENT.COMPLETED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000005
status: COMPLETED
type: OUTGOING
direction: DEBIT
source:
sourceType: ACCOUNT
accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
destination:
destinationType: ACCOUNT
accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
senderUmaAddress: $sender@uma.domain
receiverUmaAddress: $recipient@external.domain
sentAmount:
amount: 10550
currency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
receivedAmount:
amount: 9706
currency:
code: EUR
name: Euro
symbol: €
decimals: 2
exchangeRate: 0.92
quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
settledAt: '2025-08-15T14:30:00Z'
createdAt: '2025-08-15T14:25:18Z'
description: 'Payment for invoice #1234'
paymentInstructions: []
rateDetails:
counterpartyMultiplier: 1.08
counterpartyFixedFee: 10
gridApiMultiplier: 0.925
gridApiFixedFee: 10
gridApiVariableFeeRate: 0.003
gridApiVariableFeeAmount: 30
outgoingCompletedCryptoPayment:
summary: Completed crypto payout to an external wallet
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000008
type: OUTGOING_PAYMENT.COMPLETED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000009
status: COMPLETED
type: OUTGOING
direction: DEBIT
source:
sourceType: ACCOUNT
accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
destination:
destinationType: ACCOUNT
accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789
onChainTransaction:
transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx
network: SOLANA
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
sentAmount:
amount: 100000
currency:
code: USDC
name: USD Coin
symbol: ''
decimals: 6
receivedAmount:
amount: 100000
currency:
code: USDC
name: USD Coin
symbol: ''
decimals: 6
quoteId: Quote:019542f5-b3e7-1d02-0000-000000000010
settledAt: '2025-08-15T14:30:00Z'
createdAt: '2025-08-15T14:25:18Z'
description: USDC withdrawal to self-custody wallet
paymentInstructions: []
failedPayment:
summary: Failed outgoing payment
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000007
type: OUTGOING_PAYMENT.FAILED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Transaction:019542f5-b3e7-1d02-0000-000000000005
status: FAILED
type: OUTGOING
direction: DEBIT
source:
sourceType: ACCOUNT
accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
destination:
destinationType: ACCOUNT
accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 18d3e5f7b4a9c2
senderUmaAddress: $sender@uma.domain
receiverUmaAddress: $recipient@external.domain
sentAmount:
amount: 10550
currency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
createdAt: '2025-08-15T14:25:18Z'
quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
failureReason: QUOTE_EXECUTION_FAILED
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'
test-webhook:
post:
summary: Test webhook for integration verification
description: 'Webhook that is sent once to verify your webhook endpoint is correctly set up.
This is sent when you configure or update your platform settings with a webhook URL.
### Authentication
The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by the Grid API.
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.
This webhook is purely for testing your endpoint integration and signature verification.
'
operationId: testWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestWebhookRequest'
examples:
testWebhook:
summary: Test webhook example
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000001
type: TEST
timestamp: '2025-08-15T14:32:00Z'
data: {}
responses:
'200':
description: Webhook received successfully. This confirms your webhook endpoint is properly configured.
'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'
bulk-upload:
post:
summary: Bulk upload status webhook
description: 'Webhook that is called when a bulk customer upload job completes or fails.
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.
This webhook is sent when a bulk upload job completes or fails, providing detailed information about the results.
'
operationId: bulkUploadWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUploadWebhook'
examples:
completedUpload:
summary: Successful bulk upload completion
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000008
type: BULK_UPLOAD.COMPLETED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Job:019542f5-b3e7-1d02-0000-000000000006
status: COMPLETED
progress:
total: 5000
processed: 5000
successful: 5000
failed: 0
errors: []
failedUpload:
summary: Failed bulk upload
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000008
type: BULK_UPLOAD.FAILED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Job:019542f5-b3e7-1d02-0000-000000000006
status: FAILED
progress:
total: 5000
processed: 5000
successful: 0
failed: 5000
errors:
- correlationId: row_1
error:
code: invalid_csv_format
message: Invalid CSV format
details:
reason: missing_required_column
column: umaAddress
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'
invitation-claimed:
post:
summary: Invitation claimed webhook
description: 'Webhook that is called when an invitation is claimed by a customer.
This endpoint should be implemented by platform clients of the Grid API.
When a customer claims an invitation, this webhook is triggered to notify the platform that:
1. The invitation has been successfully claimed
2. The invitee UMA address is now associated with the invitation
3. The invitation status has changed from PENDING to CLAIMED
This allows platforms to:
- Track invitation usage and conversion rates
- Trigger onboarding flows for new customers who joined via invitation
- Apply referral bonuses or rewards to the inviter
- Update their UI to reflect the claimed status
### 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: invitationClaimedWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationClaimedWebhook'
examples:
claimedInvitation:
summary: Invitation claimed notification
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000008
type: INVITATION.CLAIMED
timestamp: '2025-09-01T15:45:00Z'
data:
code: 019542f5
createdAt: '2025-09-01T14:30:00Z'
claimedAt: '2025-09-01T15:45:00Z'
inviterUma: $inviter@uma.domain
inviteeUma: $invitee@uma.domain
status: CLAIMED
url: https://uma.me/i/019542f5
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'
customer-update:
post:
summary: Customer status change
description: 'Webhook that is called when the status of a customer is updated, including KYC and KYB status changes.
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 API 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: customerStatusWebhook
tags:
- Webhooks
security:
- WebhookSignature: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerWebhook'
examples:
kycApprovedWebhook:
summary: When an individual customer KYC has been approved
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000007
type: CUSTOMER.KYC_APPROVED
timestamp: '2025-08-15T14:32:00Z'
data:
id: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId: 9f84e0c2a72c4fa
customerType: INDIVIDUAL
region: US
currencies:
- USD
- USDC
umaAddress: $john.doe@uma.domain.com
kycStatus: APPROVED
fullName: John Michael Doe
birthDate: '1990-01-15'
nationality: US
address:
line1: 123 Main Street
line2: Apt 4B
city: San Francisco
state: CA
postalCode: '94105'
country: US
createdAt: '2025-07-21T17:32:28Z'
updatedAt: '2025-07-21T17:32:28Z'
isDeleted: false
kycRejectedWebhook:
summary: When an individual customer KYC has been rejected
value:
id: Webhook:019542f5-b3e7-1d02-0000-00000
# --- truncated at 32 KB (250 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspark/refs/heads/main/openapi/lightspark-webhooks-api-openapi.yml