> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook payload
The payload for a webhook is a single event referencing a resource that has recently changed.
The `target` object is a summary of that resource, captured when the event occurred. It contains
a subset of the fields that the [API](/reference) returns for the resource, and some
fields that only appear in webhooks, such as `payment_link_id` on transactions.
Gr4vy stores the payload when the event occurs, so a retried delivery sends the same
snapshot, even if the resource has changed since. Fetch the resource from the API before
you take an irreversible action, such as shipping an order, or when you need a field that
the summary doesn't include, such as a transaction's cart items or 3-D Secure details.
```json API key pair theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "api-key-pair.created",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "api-key-pair",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"thumbprint": "SopiN5XU0IWy8Xe9mwx1ICQbKh4-ydCDPx3LIyArkVI",
"display_name": "Sandbox",
"algorithm": "ECDSA",
"roles": [
{
"id": "e94fe431-b9e8-4f38-8509-f0e25be7d5a3",
"name": "Administrator",
"slug": "administrator"
}
],
"merchant_accounts": [
{
"id": "default",
"display_name": "Default"
}
],
"active": true,
"created_at": "2024-11-20T16:50:52.603191+00:00",
"updated_at": "2024-11-20T16:50:52.603191+00:00"
}
}
```
```json Buyer theme={"system"}
{
"type": "event",
"name": "buyer.created",
"id": "d99a867a-a326-447f-b61e-2825ebe6f0c5",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"created_at": "2024-11-20T16:50:52.609674+00:00",
"target": {
"type": "buyer",
"id": "f9d46f71-60d8-4b61-bddb-001a04c8224c",
"display_name": "John Smith",
"external_identifier": "user-123",
"created_at": "2024-11-20T16:50:52.603191+00:00",
"updated_at": "2024-11-20T16:50:52.603191+00:00",
"billing_details": {
"first_name": "John",
"last_name": "Smith",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "Springfield",
"country": "US",
"postal_code": "123456",
"state": "CA",
"state_code": "US-CA",
"house_number_or_name": "21",
"line1": "22nd Street",
"line2": "",
"organization": "Acme Inc"
},
"tax_id": {
"value": "12-3456789",
"kind": "us.ein"
}
}
}
}
```
```json Gift card theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "gift-card.created",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "gift-card",
"id": "00c6b82d-46d7-4d0c-b015-3f03a29b7a81",
"created_at": "2024-09-17T16:49:55.064633+00:00",
"updated_at": "2024-09-17T16:50:05.134346+00:00"
}
}
```
```json Monitoring incident theme={"system"}
{
"type": "event",
"name": "monitoring.incident.closed",
"id": "c02012f3-ac25-495c-9f75-8fbe64d701f2",
"created_at": "2026-03-03T14:54:56.485534+00:00",
"target": {
"type": "monitoring.incident",
"id": "c2e4ffaf-2463-4e8a-a9a2-b33590f3b579",
"spec": {
"model": "auth_rate",
"params": {
"filters": {
"datetime_range": "PT60M/hour_start",
"payment_method_bin": ["123456", "411111"],
"payment_method_scheme": ["visa"]
}
}
},
"alerting_policy": {
"strategy": "threshold",
"params": {
"alert_gt": 99.9,
"alert_lt": 90
}
},
"incident_policy": {
"strategy": "debouncing",
"params": {
"create_after_n": 3,
"close_after_n": 6
}
},
"notes": "PSP-related incident",
"created_at": "2025-10-28T11:47:32.566063+00:00",
"updated_at": "2025-10-28T12:03:05.120019+00:00",
"closed_at": "2025-10-28T11:57:32.566063+00:00"
},
"merchant_account_id": "default",
"gr4vy_id": "dev",
"environment": "sandbox"
}
```
```json Payment link theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "payment-link.updated",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "payment-link",
"id": "8d29457b-683a-49c4-8afd-800cd7117236",
"amount": 1299,
"currency": "GBP",
"country": "GB",
"intent": "authorize",
"payment_source": "ecommerce",
"external_identifier": null,
"expires_at": "2024-09-24T16:57:48.393644+00:00",
"created_at": "2024-09-17T16:57:48.393644+00:00",
"updated_at": "2024-09-17T16:57:50.553736+00:00"
}
}
```
```json Payment method theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "payment-method.updated",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "payment-method",
"id": "8d29457b-683a-49c4-8afd-800cd7117236",
"status": "succeeded",
"method": "card",
"external_identifier": null,
"created_at": "2024-09-17T16:57:48.393644+00:00",
"updated_at": "2024-09-17T16:57:50.553736+00:00"
}
}
```
```json Payout theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "payout.succeeded",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "payout",
"id": "a994ec53-23b3-42e5-ab44-e4942d8aa7ba",
"payout_id": "7ef82ff4-5862-4d2b-8bd0-4cbf86668fc5",
"external_identifier": "payout-234",
"payment_service_payout_id": "148206c4-fc32-44f3-906a-3d1b35865c19",
"payment_service_id": "4504fa23-4318-44cd-95f5-872e6dabc9bc",
"amount": 1299,
"currency": "GBP",
"status": "succeeded",
"created_at": "2024-11-07T11:07:18.955537+00:00",
"updated_at": "2024-11-07T11:07:19.111351+00:00"
}
}
```
```json Refund theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "refund.succeeded",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "refund",
"id": "a994ec53-23b3-42e5-ab44-e4942d8aa7ba",
"transaction_id": "7ef82ff4-5862-4d2b-8bd0-4cbf86668fc5",
"payment_service_refund_id": "148206c4-fc32-44f3-906a-3d1b35865c19",
"amount": 1299,
"currency": "GBP",
"status": "succeeded",
"target_id": null,
"created_at": "2024-11-07T11:07:18.955537+00:00",
"updated_at": "2024-11-07T11:07:19.111351+00:00",
"transaction_external_identifier": "tx-123",
"external_identifier": "refund-234",
"target_type": "payment-method",
"reconciliation_id": "59zlCXgKuGfCz0wc8cTnOk",
"transaction_reconciliation_id": "3raSDUgac8qWle5IbcZiMP",
"error_code": null,
"reason": null
}
}
```
```json Report theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "report-execution.succeeded",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "report-execution",
"id": "8d29457b-683a-49c4-8afd-800cd7117236",
"status": "succeeded",
"report": {
"type": "report",
"id": "5b98970d-c6ee-48f1-a096-c5d37761f329"
},
"created_at": "2024-09-17T16:49:55.064633+00:00",
"updated_at": "2024-09-17T16:50:05.134346+00:00"
}
}
```
```json Shipping details theme={"system"}
{
"type": "event",
"name": "shipping-details.created",
"id": "702863ee-fd78-467d-a0a7-533bf429b39c",
"created_at": "2024-11-20T12:48:38.409619+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "shipping-details",
"id": "3dda8d7a-e7cd-43b8-9128-21adf1ec868b",
"buyer_id": "baa7b3b3-a4f1-49e3-afb0-0f41b48f5aa2",
"first_name": "John",
"last_name": "Smith",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "Springfield",
"country": "US",
"postal_code": "123456",
"state": "CA",
"state_code": "US-CA",
"house_number_or_name": "21",
"line1": "22nd Street",
"line2": "",
"organization": "Acme Inc"
},
"created_at": "2024-11-20T12:48:38.402474+00:00",
"updated_at": "2024-11-20T12:48:38.402474+00:00"
}
}
```
```json Transaction theme={"system"}
{
"type": "event",
"id": "347901e1-8b53-42a4-951b-ec546a5078f1",
"name": "transaction.authorized",
"created_at": "2012-12-12T10:53:43+00:00",
"merchant_account_id": "default",
"gr4vy_id": "example",
"environment": "sandbox",
"target": {
"type": "transaction",
"id": "95c27e9d-6cc3-40f6-a359-1355c434c30d",
"external_identifier": "order-1234",
"payment_service_transaction_id": "8110000000002017185",
"status": "authorization_succeeded",
"has_gift_card_redemptions": false,
"pending_review": false,
"amount": 1299,
"authorized_amount": 1299,
"captured_amount": 0,
"refunded_amount": 0,
"currency": "USD",
"metadata": {
"profile": "profile-1234"
},
"created_at": "2024-09-17T16:54:57.333316+00:00",
"updated_at": "2024-09-17T16:55:06.560721+00:00",
"payment_method": {
"id": "852b951c-d7ea-4c98-b09e-4a1c9e97c077",
"method": "card",
"label": "1111",
"scheme": "visa"
},
"payment_link_id": null,
"error_code": null,
"iso_response_code": "00",
"payment_source": "ecommerce",
"merchant_initiated": false,
"is_subsequent_payment": false,
"buyer": {
"id": "f9d46f71-60d8-4b61-bddb-001a04c8224c",
"display_name": "John Smith",
"external_identifier": "user-123",
"account_number": null,
"billing_details": {
"first_name": "John",
"last_name": "Smith",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "Springfield",
"country": "US",
"postal_code": "123456",
"state": "CA",
"state_code": "US-CA",
"house_number_or_name": "21",
"line1": "22nd Street",
"line2": "",
"organization": "Acme Inc"
},
"tax_id": null
}
}
}
}
```
## Transaction payloads
In a transaction event, `payment_method` is `null` when the transaction has no payment
method. `buyer` is `null` unless the transaction has at least one of a buyer ID, display name,
external identifier, account number, or billing details. A guest checkout can have billing
details without a buyer, in which case `buyer.id` is `null`.
Transaction payloads can contain personal data, such as the buyer's name, email address,
phone number, and address, and any personal data you put in `metadata`. Mask or remove
these fields before you log a webhook payload.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.