Wallet operation completed or failed

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 payload is self-contained — handle it from the fields below with no follow-up API call needed.

The specific operation is carried in data.operationType (auth_credential.create, auth_credential.delete, session.revoke, wallet.export, or customer.contact_update), and the business resource it affected is carried in data.resourceType / data.resourceId:

operationType	resourceType	resourceId identifies
auth_credential.create	AUTH_METHOD	the created credential — its id can’t be known before this webhook, since the create request has nothing to echo
auth_credential.delete	AUTH_METHOD	the deleted credential
session.revoke	SESSION	the revoked session
wallet.export	INTERNAL_ACCOUNT	the account whose wallet was exported
customer.contact_update	CUSTOMER	the customer whose email or phone number changed

The webhook carries no sensitive result material — for wallet.export, the export bundle itself is never delivered here; retrieve it by resubmitting the original signed export request until it returns the result.

Correlating this webhook

• data.requestId is the primary correlation key. It is the same Request-Id value you supplied on the signed retry that produced this terminal result — echo it against the Request-Id you sent (and, if you polled through one or more 200 { status: "PROCESSING" } responses, against the value you kept resending).
• data.resourceId is the primary correlator for the business resource itself, distinct from requestId’s role of matching the request. For auth_credential.create this is the only way to learn the created credential’s id — the request that created it had nothing to echo.
• id (the top-level webhook envelope id) is for deduplication. Grid may redeliver a webhook after a transient failure; track id to avoid double-processing.
• data.operationId is a Grid-internal identifier for the operation. It’s useful when contacting support about a specific operation, but isn’t intended as a correlation key.

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.

WEBHOOK wallet-operation

JSON

completed

{
  "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",
    "requestId": "Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45",
    "operationType": "wallet.export",
    "resourceType": "INTERNAL_ACCOUNT",
    "resourceId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000005",
    "status": "completed"
  }
}

400

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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:

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.

Body

application/json

id · string · required

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

Example:

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

type · enum<string> · required

Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED)

Available options: WALLET_OPERATION.COMPLETED, WALLET_OPERATION.FAILED

timestamp · string<date-time> · required

ISO 8601 timestamp of when the webhook was sent

Example:

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

data · Wallet Operation Completed Data · object · required

Wallet Operation Completed Data

Wallet Operation Failed Data

Show child attributes

Response

200

Webhook received successfully