List webhook events - Coinbase Developer Documentation

List webhook events

curl --request GET \
  --url https://payments.coinbase.com/api/v1/webhook-events \
  --header 'Authorization: <api-key>'

{
  "webhookEvents": [
    {
      "entity": "<string>",
      "id": "<string>",
      "eventType": "EVENT_TYPE_PAYMENT_AUTHORIZED",
      "operationType": "OPERATION_TYPE_PAYMENT",
      "paymentOperation": {
        "entity": "<string>",
        "id": "<string>",
        "transactionHash": "<string>",
        "params": {},
        "status": "PAYMENT_OPERATION_STATUS_SUCCEEDED",
        "action": "PAYMENT_OPERATION_ACTION_AUTHORIZE",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "payment": {
          "entity": "<string>",
          "id": "<string>",
          "maxAmount": "<string>",
          "token": "<string>",
          "networkId": 123,
          "payer": "<string>",
          "signature": "<string>",
          "receiver": "<string>",
          "maxFeeBps": 123,
          "minFeeBps": 123,
          "feeReceiver": "<string>",
          "salt": "<string>",
          "paymentInfoHash": "<string>",
          "nonce": "<string>",
          "authorizationExpiry": "<string>",
          "preApprovalExpiry": "<string>",
          "refundExpiry": "<string>",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z",
          "operator": "<string>",
          "contractAddress": "<string>",
          "authorizedAmount": "<string>",
          "capturedAmount": "<string>",
          "voidedAmount": "<string>",
          "refundedAmount": "<string>",
          "chargedAmount": "<string>",
          "merchantId": "<string>"
        },
        "output": "<string>",
        "error": "<string>",
        "errorCode": "<string>",
        "revertReason": "<string>",
        "blockNumber": "<string>",
        "metadata": {}
      },
      "rewardOperation": {
        "id": "<string>",
        "action": "REWARD_OPERATION_ACTION_ALLOCATE",
        "status": "REWARD_OPERATION_STATUS_PENDING",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "reward": {
          "id": "<string>",
          "campaignAddress": "<string>",
          "paymentInfoHash": "<string>",
          "recipientAddress": "<string>",
          "tokenAddress": "<string>",
          "chainId": 123,
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        },
        "amount": "<string>",
        "transactionHash": "<string>",
        "error": "<string>",
        "errorCode": "<string>",
        "revertReason": "<string>",
        "blockNumber": "<string>"
      },
      "webhook": {
        "entity": "<string>",
        "id": "<string>",
        "operatorCoinbaseUserId": "<string>",
        "identifier": "<string>",
        "description": "<string>",
        "url": "<string>",
        "events": [
          "EVENT_TYPE_PAYMENT_AUTHORIZED"
        ],
        "secret": "<string>",
        "status": "WEBHOOK_STATUS_ACTIVATED",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "source": "WEBHOOK_SOURCE_OPERATOR",
      "attempts": 123,
      "maxRetries": 123,
      "apiVersion": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "deliveredAt": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "limit": 123,
    "next": "<string>"
  }
}

GET

api

webhook-events

List webhook events

curl --request GET \
  --url https://payments.coinbase.com/api/v1/webhook-events \
  --header 'Authorization: <api-key>'

{
  "webhookEvents": [
    {
      "entity": "<string>",
      "id": "<string>",
      "eventType": "EVENT_TYPE_PAYMENT_AUTHORIZED",
      "operationType": "OPERATION_TYPE_PAYMENT",
      "paymentOperation": {
        "entity": "<string>",
        "id": "<string>",
        "transactionHash": "<string>",
        "params": {},
        "status": "PAYMENT_OPERATION_STATUS_SUCCEEDED",
        "action": "PAYMENT_OPERATION_ACTION_AUTHORIZE",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "payment": {
          "entity": "<string>",
          "id": "<string>",
          "maxAmount": "<string>",
          "token": "<string>",
          "networkId": 123,
          "payer": "<string>",
          "signature": "<string>",
          "receiver": "<string>",
          "maxFeeBps": 123,
          "minFeeBps": 123,
          "feeReceiver": "<string>",
          "salt": "<string>",
          "paymentInfoHash": "<string>",
          "nonce": "<string>",
          "authorizationExpiry": "<string>",
          "preApprovalExpiry": "<string>",
          "refundExpiry": "<string>",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z",
          "operator": "<string>",
          "contractAddress": "<string>",
          "authorizedAmount": "<string>",
          "capturedAmount": "<string>",
          "voidedAmount": "<string>",
          "refundedAmount": "<string>",
          "chargedAmount": "<string>",
          "merchantId": "<string>"
        },
        "output": "<string>",
        "error": "<string>",
        "errorCode": "<string>",
        "revertReason": "<string>",
        "blockNumber": "<string>",
        "metadata": {}
      },
      "rewardOperation": {
        "id": "<string>",
        "action": "REWARD_OPERATION_ACTION_ALLOCATE",
        "status": "REWARD_OPERATION_STATUS_PENDING",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "reward": {
          "id": "<string>",
          "campaignAddress": "<string>",
          "paymentInfoHash": "<string>",
          "recipientAddress": "<string>",
          "tokenAddress": "<string>",
          "chainId": 123,
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        },
        "amount": "<string>",
        "transactionHash": "<string>",
        "error": "<string>",
        "errorCode": "<string>",
        "revertReason": "<string>",
        "blockNumber": "<string>"
      },
      "webhook": {
        "entity": "<string>",
        "id": "<string>",
        "operatorCoinbaseUserId": "<string>",
        "identifier": "<string>",
        "description": "<string>",
        "url": "<string>",
        "events": [
          "EVENT_TYPE_PAYMENT_AUTHORIZED"
        ],
        "secret": "<string>",
        "status": "WEBHOOK_STATUS_ACTIVATED",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "source": "WEBHOOK_SOURCE_OPERATOR",
      "attempts": 123,
      "maxRetries": 123,
      "apiVersion": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "deliveredAt": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "limit": 123,
    "next": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal.

Query Parameters

limit

integer<int32>

Limit

Maximum number of webhook events to return. Default is 10, Max is 25.

string

Next item to use for pagination.

Response

A successful response.

List of webhook events .

webhookEvents

WebhookEvent · object[]

required

List of webhook events.

Show child attributes

webhookEvents.entity

string

webhookEvents.id

string

webhookEvents.eventType

enum<string>

List of supported events.

Available options:

EVENT_TYPE_PAYMENT_AUTHORIZED,

EVENT_TYPE_PAYMENT_CAPTURED,

EVENT_TYPE_PAYMENT_VOIDED,

EVENT_TYPE_PAYMENT_REFUNDED,

EVENT_TYPE_PAYMENT_CHARGED,

EVENT_TYPE_REWARD_ALLOCATED,

EVENT_TYPE_REWARD_DISTRIBUTED,

EVENT_TYPE_REWARD_DEALLOCATED,

EVENT_TYPE_REWARD_SENT,

EVENT_TYPE_PAYMENT_RECONCILED

webhookEvents.operationType

enum<string>

Type of operation that triggered the webhook.

Available options:

OPERATION_TYPE_PAYMENT,

OPERATION_TYPE_REWARD

webhookEvents.paymentOperation

PaymentOperation · object

Event details related to a payment including transaction hash, status, and associated payment information.

Show child attributes

webhookEvents.paymentOperation.entity

string

required

Entity type, e.g., 'payment-operation'.

webhookEvents.paymentOperation.id

string

required

Unique event ID.

webhookEvents.paymentOperation.transactionHash

string

required

Blockchain transaction hash.

webhookEvents.paymentOperation.params

Params · object

required

Payment Operation Parameters.

Show child attributes

webhookEvents.paymentOperation.params.{key}

string

webhookEvents.paymentOperation.status

enum<string>

required

Payment Operation status.

Available options:

PAYMENT_OPERATION_STATUS_SUCCEEDED,

PAYMENT_OPERATION_STATUS_FAILED,

PAYMENT_OPERATION_STATUS_PENDING

webhookEvents.paymentOperation.action

enum<string>

required

Type of action (e.g., PAYMENT_OPERATION_ACTION_AUTHORIZE).

Available options:

PAYMENT_OPERATION_ACTION_AUTHORIZE,

PAYMENT_OPERATION_ACTION_CAPTURE,

PAYMENT_OPERATION_ACTION_CHARGE,

PAYMENT_OPERATION_ACTION_RECLAIM,

PAYMENT_OPERATION_ACTION_REFUND,

PAYMENT_OPERATION_ACTION_VOID

webhookEvents.paymentOperation.createdAt

string<date-time>

required

Event creation timestamp.

webhookEvents.paymentOperation.updatedAt

string<date-time>

required

Event update timestamp.

webhookEvents.paymentOperation.payment

Payment · object

required

Detailed payment object.

Show child attributes

webhookEvents.paymentOperation.payment.entity

string

required

Entity type, e.g., 'payment'.

webhookEvents.paymentOperation.payment.id

string

required

Unique payment ID.

webhookEvents.paymentOperation.payment.maxAmount

string

required

Max payment amount approved by the buyer.

webhookEvents.paymentOperation.payment.token

string

required

Token address used.

webhookEvents.paymentOperation.payment.networkId

integer<int32>

required

Identifier for the blockchain network.

webhookEvents.paymentOperation.payment.payer

string

required

Payer's EVM address.

webhookEvents.paymentOperation.payment.signature

string

required

Digital signature of the preapproved amount signed by the buyer.

webhookEvents.paymentOperation.payment.receiver

string

required

Receiver's EVM address.

webhookEvents.paymentOperation.payment.maxFeeBps

integer<int32>

required

Max fee in basis points.

webhookEvents.paymentOperation.payment.minFeeBps

integer<int32>

required

Min fee in basis points.

webhookEvents.paymentOperation.payment.feeReceiver

string

required

Fee recipient address.

webhookEvents.paymentOperation.payment.salt

string

required

Unique salt to prevent duplicate preapproval authorizations.

webhookEvents.paymentOperation.payment.paymentInfoHash

string

required

Hash of the payment info.

webhookEvents.paymentOperation.payment.nonce

string

required

Nonce in the Preapproval Authorization.

webhookEvents.paymentOperation.payment.authorizationExpiry

string<int64>

required

Expiry time for the authorization.

webhookEvents.paymentOperation.payment.preApprovalExpiry

string<int64>

required

Expiry time for preapproval

webhookEvents.paymentOperation.payment.refundExpiry

string<int64>

required

Expiry time for refund

webhookEvents.paymentOperation.payment.createdAt

string<date-time>

required

Creation timestamp.

webhookEvents.paymentOperation.payment.updatedAt

string<date-time>

required

Last update timestamp.

webhookEvents.paymentOperation.payment.operator

string

required

Operator handling the payment.

webhookEvents.paymentOperation.payment.contractAddress

string

required

Smart contract address of the Commerce PaymentEscrow protocol

webhookEvents.paymentOperation.payment.authorizedAmount

string

required

Authorized payment amount.

webhookEvents.paymentOperation.payment.capturedAmount

string

required

Captured payment amount.

webhookEvents.paymentOperation.payment.voidedAmount

string

required

Voided payment amount.

webhookEvents.paymentOperation.payment.refundedAmount

string

required

Refunded payment amount.

webhookEvents.paymentOperation.payment.chargedAmount

string

required

Charged payment amount.

webhookEvents.paymentOperation.payment.merchantId

string

required

Merchant ID.

webhookEvents.paymentOperation.output

string

Output of the payment operation.

webhookEvents.paymentOperation.error

string

Error of the payment operation.

webhookEvents.paymentOperation.errorCode

string

Error code of the payment operation.

webhookEvents.paymentOperation.revertReason

string

Blockchain revert reason of the payment operation.

webhookEvents.paymentOperation.blockNumber

string<int64>

Block number of the payment operation.

webhookEvents.paymentOperation.metadata

Metadata · object

Additional metadata as a free-form object.

webhookEvents.rewardOperation

RewardOperation · object

Operation details related to a reward including transaction hash, status, and associated reward information.

Show child attributes

webhookEvents.rewardOperation.id

string

required

Unique identifier for the reward operation.

webhookEvents.rewardOperation.action

enum<string>

required

Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE).

Available options:

REWARD_OPERATION_ACTION_ALLOCATE,

REWARD_OPERATION_ACTION_DEALLOCATE,

REWARD_OPERATION_ACTION_DISTRIBUTE,

REWARD_OPERATION_ACTION_SEND

webhookEvents.rewardOperation.status

enum<string>

required

Current status of the reward operation.

Available options:

REWARD_OPERATION_STATUS_PENDING,

REWARD_OPERATION_STATUS_SUCCEEDED,

REWARD_OPERATION_STATUS_FAILED

webhookEvents.rewardOperation.createdAt

string<date-time>

required

Timestamp when the reward operation was created.

webhookEvents.rewardOperation.updatedAt

string<date-time>

required

Timestamp when the reward operation was last updated.

webhookEvents.rewardOperation.reward

Reward · object

Detailed reward object associated with this operation.

Show child attributes

webhookEvents.rewardOperation.reward.id

string

required

Unique identifier for the reward.

webhookEvents.rewardOperation.reward.campaignAddress

string

required

Onchain address of the campaign contract.

webhookEvents.rewardOperation.reward.paymentInfoHash

string

required

Hash of the payment info that this reward is associated with.

webhookEvents.rewardOperation.reward.recipientAddress

string

required

Blockchain address that will receive the reward.

webhookEvents.rewardOperation.reward.tokenAddress

string

required

Address of the token contract used for the reward.

webhookEvents.rewardOperation.reward.chainId

integer<int32>

required

The blockchain network identifier where the reward is processed.

webhookEvents.rewardOperation.reward.createdAt

string<date-time>

required

Timestamp when the reward was created.

webhookEvents.rewardOperation.reward.updatedAt

string<date-time>

required

Timestamp when the reward was last updated.

webhookEvents.rewardOperation.amount

string

Amount involved in this reward operation.

webhookEvents.rewardOperation.transactionHash

string

Blockchain transaction hash for this reward operation.

webhookEvents.rewardOperation.error

string

Error message if the reward operation failed.

webhookEvents.rewardOperation.errorCode

string

Error code of the reward operation.

webhookEvents.rewardOperation.revertReason

string

Blockchain revert reason of the reward operation.

webhookEvents.rewardOperation.blockNumber

string<int64>

Block number of the reward operation.

webhookEvents.webhook

Webhook · object

Webhook configuration details.

Show child attributes

webhookEvents.webhook.entity

string

Type of the entity, always "webhook".

webhookEvents.webhook.id

string

Unique identifier for the webhook.

webhookEvents.webhook.operatorCoinbaseUserId

string

Coinbase user ID of the operator this webhook belongs to.

webhookEvents.webhook.identifier

string

External identifier for clients.

webhookEvents.webhook.description

string

Human-readable description of the webhook's purpose.

webhookEvents.webhook.url

string

The URL where webhook events will be sent.

webhookEvents.webhook.events

enum<string>[]

Types of events this webhook should receive.

List of supported events.

Available options:

EVENT_TYPE_PAYMENT_AUTHORIZED,

EVENT_TYPE_PAYMENT_CAPTURED,

EVENT_TYPE_PAYMENT_VOIDED,

EVENT_TYPE_PAYMENT_REFUNDED,

EVENT_TYPE_PAYMENT_CHARGED,

EVENT_TYPE_REWARD_ALLOCATED,

EVENT_TYPE_REWARD_DISTRIBUTED,

EVENT_TYPE_REWARD_DEALLOCATED,

EVENT_TYPE_REWARD_SENT,

EVENT_TYPE_PAYMENT_RECONCILED

webhookEvents.webhook.secret

string

Secret used for webhook signature verification.

webhookEvents.webhook.status

enum<string>

Status of the webhook (active, inactive).

Available options:

WEBHOOK_STATUS_ACTIVATED,

WEBHOOK_STATUS_DEACTIVATED

webhookEvents.webhook.createdAt

string<date-time>

When the webhook was created.

webhookEvents.webhook.updatedAt

string<date-time>

When the webhook was last updated.

webhookEvents.source

enum<string>

List of webhook sources.

Available options:

WEBHOOK_SOURCE_OPERATOR,

WEBHOOK_SOURCE_INDEXER

webhookEvents.attempts

integer<int32>

webhookEvents.maxRetries

integer<int32>

webhookEvents.apiVersion

string

webhookEvents.createdAt

string<date-time>

webhookEvents.deliveredAt

string<date-time>

webhookEvents.metadata

object

pagination

Pagination · object

required

Pagination information for the response.

Show child attributes

pagination.limit

integer<int32>

required

Number of items per page in this response.

pagination.next

string

required

Next item to use for pagination.

Update webhook

Get webhook events by payment operation ID

⌘I

PAYMENT ACCEPTANCE

Authorizations

Query Parameters

Response