Invitation claimed webhook

Authorizations

X-Grid-Signature

string

header

required

Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid.

To verify the signature:

Get the Grid public key provided to you during integration
Decode the base64 signature from the header
Create a SHA-256 hash of the request body
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.

Body

application/json

timestamp

string<date-time>

required

ISO8601 timestamp when the webhook was sent (can be used to prevent replay attacks)

Example:

"2025-08-15T14:32:00Z"

webhookId

string

required

Unique identifier for this webhook delivery (can be used for idempotency)

Example:

"Webhook:019542f5-b3e7-1d02-0000-000000000007"

type

enum<string>

required

Type of webhook event Type of webhook event

Available options:

INVITATION_CLAIMED

Example:

"INVITATION_CLAIMED"

invitation

object

required

Show child attributes

invitation.code

string

required

The unique code of the invitation

Example:

"019542f5"

invitation.createdAt

string<date-time>

required

When the invitation was created

Example:

"2025-09-01T14:30:00Z"

invitation.url

string

required

The URL where this invitation can be claimed.

Example:

"https://uma.me/i/019542f5"

invitation.inviterUma

string

required

The UMA address of the inviter

Example:

"[email protected]"

invitation.status

enum<string>

required

The status of the invitation

Available options:

PENDING,

CLAIMED,

EXPIRED,

CANCELLED

Example:

"PENDING"

invitation.claimedAt

string<date-time>

When the invitation was claimed if it has been claimed

Example:

"2025-09-01T14:30:00Z"

invitation.expiresAt

string<date-time>

When the invitation expires (if at all)

Example:

"2025-09-01T14:30:00Z"

invitation.inviteeUma

string

The UMA address of the invitee

Example:

"[email protected]"

invitation.firstName

string

The inviter's first name. Will be displayed when the recipient clicks the invite link

Example:

"Jane"

invitation.amountToSend

object

The amount to send to the invitee when the invitation is claimed. This is optional and if not provided, the invitee will not receive any amount. Note that the actual sending of the amount must be done by the inviter platform once the INVITATION_CLAIMED webhook is received. If the inviter platform either does not send the payment or the payment fails, the invitee will not receive this amount. This field is primarily used for display purposes on the claiming side of the invitation. This field is useful for "send-by-link" style customer flows where an inviter can send a payment simply by sharing a link without knowing the receiver's UMA address. Note that these sends can only be sender-locked, meaning that the sender will not know ahead of time how much the receiver will receive in the receiving currency.

Show child attributes

invitation.amountToSend.amount

integer<int64>

required

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example:

12550

invitation.amountToSend.currency

object

required

Show child attributes

invitation.amountToSend.currency.code

string

Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)

Example:

"USD"

invitation.amountToSend.currency.name

string

Full name of the currency

Example:

"United States Dollar"

invitation.amountToSend.currency.symbol

string

Symbol of the currency

Example:

"$"

invitation.amountToSend.currency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

Response

Webhook received successfully

Using the API

API documentation

Authentication

Authorizations

Body

Response