Skip to main content

Sign in with Coinbase Notifications API

Table of Endpoints

NameMethodEndpointScope
List NotificationsGET/v2/notificationswallet:addresses:new-payment
Show NotificationGET/v2/notifications/:notifications_idwallet:notifications:read

Overview

Notifications let you subscribe to OAuth and API key updates. Notifications are sent as HTTP POST requests (webhooks) to a notification endpoint, which the developer can set for their OAuth application or API key settings.

Each notification contains the following information:

  • Type - Action that triggered the event
  • Data - Data of the resource at the time of the event
  • Additional data - Additional data associated with the event
  • User - Owner of the resource (useful with OAuth applications)
  • Account - Account of the resource
  • Delivery information

If notification delivery fails, it is re-tried hourly for up to three days. If you ever need to access notifications afterwards, you can query them using notification API endpoints. Content of the notification will not change even if the referenced resource changes over time.

To secure your notifications, you should obfuscate your notification URL and verify the origin of the callback by validating it against the Coinbase callback IP addresses and signature (CB-SIGNATURE header). See notifications.

Outbound notifications (webhooks) are versioned using API version defined in user's API settings.

Supported Notification Types

Each type is named with service:resource:action. For example, confirming a buy on the Wallet API is wallet:buys:completed.

To protect sensitive information, read permission for the resource is required to receive notifications for the resource type. For example, an API key needs to have wallet:buys:read permission to receive a notification for wallet:buys:completed.

Notification TypeRequired PermissionDescription
pingNoneSend at any time to verify that the notification URL works
wallet:addresses:new-paymentwallet:addresses:readNew payment has been made to an on-chain crypto address
wallet:buys:createdwallet:buys:read or wallet:buys:createA buy has been created
wallet:buys:completedwallet:buys:read or wallet:buys:createA buy has been completed
wallet:buys:canceledwallet:buys:read or wallet:buys:createA buy has been canceled
wallet:sells:createdwallet:sells:read or wallet:sells:createA sell has been created
wallet:sells:completedwallet:sells:read or wallet:sells:createA sell has been completed
wallet:sells:canceledwallet:sells:read or wallet:sells:createA sell has been canceled
wallet:deposits:createdwallet:deposits:read or wallet:deposits:createA deposit has been created
wallet:deposits:completedwallet:deposits:read or wallet:deposits:createA deposit has been completed
wallet:deposits:canceledwallet:deposits:read or wallet:deposits:createA deposit has been canceled
wallet:withdrawals:createdwallet:withdrawals:read or wallet:withdrawals:createA withdrawal has been created
wallet:withdrawals:completedwallet:withdrawals:read or wallet:withdrawals:createA withdrawal has been completed
wallet:withdrawals:canceledwallet:withdrawals:read or wallet:withdrawals:createA withdrawal has been canceled
FieldsDescription
id stringResource ID
type stringNotification type
data hash, optionalNotification data. You can also use resource key with other available data. For type: ping, data is an empty hash.
user hashRelated user (useful when separating OAuth notifications)
account hashRelated account
delivery_attempts integerNumber of delivery attempts (excluded from webhook)
delivery_response hashInformation about last delivery (excluded from webhook)
created_at timestamp
updated_at timestamp
resource string, constant notification
resource_path string
subscriber hashSeparate different notification subsribers in list notifications endpoint

New Payment

New payment to a Bitcoin Address.

Scope

wallet:addresses:new-payment

Example Response

{
"id": "5a6956f9-94bb-5c15-99f3-a2a690347674",
"type": "wallet:addresses:new-payment",
"data": {
"id": "c556eec7-53c2-576c-9158-c2eaa7c7ffca",
"address": "mr4xYGzGMnw5tbbu2qyBBGdKwA4ktufbPy",
"name": null,
"created_at": "2015-01-31T20:49:02Z",
"updated_at": "2015-01-31T20:49:02Z",
"resource": "address",
"resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6/addresses/c556eec7-53c2-576c-9158-c2eaa7c7ffca"
},
"user": {
"id": "5b5b60b6-2cd3-5f88-8539-3a78cd111b49",
"resource": "user",
"resource_path": "/v2/users/5b5b60b6-2cd3-5f88-8539-3a78cd111b49"
},
"account": {
"id": "c334783a-e72c-5e25-bf43-e182345f28c6",
"resource": "account",
"resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6"
},
"delivery_attempts": 0,
"created_at": "2015-01-31T20:49:02Z",
"resource": "notification",
"resource_path": "/v2/notifications/5a6956f9-94bb-5c15-99f3-a2a690347674",
"additional_data": {
"hash": "749f267f9d238c978fe3e79a6c1f34070b0b8e5a3de8623d1bd144760bf79a5f",
"amount": {
"amount": "0.10000000",
"currency": "BTC"
},
"transaction": {
"id": "fe7b729d-62c6-5978-95ca-6cc1f9d23119",
"resource": "transaction",
"resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6/transactions/fe7b729d-62c6-5978-95ca-6cc1f9d23119"
}
}
}

Completed Buy

Scope

wallet:buys:completed

Example Response

{
"id": "6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338",
"type": "wallet:buys:completed",
"data": {
"id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
"status": "completed",
"payment_method": {
"id": "83562370-3e5c-51db-87da-752af5ab9559",
"resource": "payment_method",
"resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
},
"transaction": {
"id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
},
"amount": {
"amount": "1.00000000",
"currency": "BTC"
},
"total": {
"amount": "10.25",
"currency": "USD"
},
"subtotal": {
"amount": "10.10",
"currency": "USD"
},
"created_at": "2015-01-31T20:49:02Z",
"updated_at": "2015-02-11T16:54:02-08:00",
"resource": "buy",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
"committed": true,
"instant": false,
"fee": {
"amount": "0.15",
"currency": "USD"
},
"payout_at": "2015-02-18T16:54:00-08:00"
},
"additional_data": {},
"user": {
"id": "f01c821e-bb35-555f-a4da-548672963119",
"resource": "user",
"resource_path": "/v2/users/f01c821e-bb35-555f-a4da-548672963119"
},
"account": {
"id": "8d5f086c-d7d5-58ee-890e-c09b3d8d4434",
"resource": "account",
"resource_path": "/v2/accounts/8d5f086c-d7d5-58ee-890e-c09b3d8d4434"
},
"delivery_attempts": 0,
"created_at": "2015-11-10T19:15:06Z",
"resource": "notification",
"resource_path": "/v2/notifications/6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338"
}

List Notifications

Lists notifications where the current user was the subscriber (owner of the API key or OAuth application).

HTTP Request

GET https://api.coinbase.com/v2/notifications

Scope

wallet:notifications:read

Examples

Request

curl https://api.coinbase.com/v2/notifications \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Show Notification

Show a notification for which the current user was a subsciber.

HTTP Request

GET https://api.coinbase.com/v2/notifications/:notifications_id

Scope

wallet:notifications:read

Examples

Request

curl https://api.coinbase.com/v2/notifications/0fdfb26e-bd26-5e1c-b055-7b935e57fa33 \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Response

{
"data":
{
"id": "6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338",
"type": "wallet:buys:completed",
"data": {
"id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
"status": "completed",
"payment_method": {
"id": "83562370-3e5c-51db-87da-752af5ab9559",
"resource": "payment_method",
"resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
},
"transaction": {
"id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
},
"amount": {
"amount": "1.00000000",
"currency": "BTC"
},
"total": {
"amount": "10.25",
"currency": "USD"
},
"subtotal": {
"amount": "10.10",
"currency": "USD"
},
"created_at": "2015-01-31T20:49:02Z",
"updated_at": "2015-02-11T16:54:02-08:00",
"resource": "buy",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
"committed": true,
"instant": false,
"fee": {
"amount": "0.15",
"currency": "USD"
},
"payout_at": "2015-02-18T16:54:00-08:00"
},
"user": {
"id": "f01c821e-bb35-555f-a4da-548672963119",
"resource": "user",
"resource_path": "/v2/users/f01c821e-bb35-555f-a4da-548672963119"
},
"account": {
"id": "8d5f086c-d7d5-58ee-890e-c09b3d8d4434",
"resource": "account",
"resource_path": "/v2/accounts/8d5f086c-d7d5-58ee-890e-c09b3d8d4434"
},
"delivery_attempts": 0,
"created_at": "2015-11-10T19:15:06Z",
"resource": "notification",
"resource_path": "/v2/notifications/6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338"
}
}

Was this helpful?