Notifications
Notification Resource
Notifications allow you to subscribe to updates regarding your OAuth application or API key. 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 will be re-tried hourly 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).
Read more about notifications.
Outbound notifications (webhooks) are versioned using API version defined in user's API settings.
Listed below are notification types that are currently supported. 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
. There are some exceptions to this rule, but each supported notification type is listed below with its corresponding required permissions.
Only notifications listed below are currently supported. We'll add more notifications over time.
Notification type | Required permission | Description |
---|---|---|
ping | None | Send at any time to verify that the notification URL works |
wallet:addresses:new-payment | wallet:addresses:read | New payment has been made to an on-chain crypto address |
wallet:buys:created | wallet:buys:read or wallet:buys:create | A buy has been created |
wallet:buys:completed | wallet:buys:read or wallet:buys:create | A buy has been completed |
wallet:buys:canceled | wallet:buys:read or wallet:buys:create | A buy has been canceled |
wallet:sells:created | wallet:sells:read or wallet:sells:create | A sell has been created |
wallet:sells:completed | wallet:sells:read or wallet:sells:create | A sell has been completed |
wallet:sells:canceled | wallet:sells:read or wallet:sells:create | A sell has been canceled |
wallet:deposits:created | wallet:deposits:read or wallet:deposits:create | A deposit has been created |
wallet:deposits:completed | wallet:deposits:read or wallet:deposits:create | A deposit has been completed |
wallet:deposits:canceled | wallet:deposits:read or wallet:deposits:create | A deposit has been canceled |
wallet:withdrawals:created | wallet:withdrawals:read or wallet:withdrawals:create | A withdrawal has been created |
wallet:withdrawals:completed | wallet:withdrawals:read or wallet:withdrawals:create | A withdrawal has been completed |
wallet:withdrawals:canceled | wallet:withdrawals:read or wallet:withdrawals:create | A withdrawal has been canceled |
Fields | Description |
---|---|
id string | Resource ID |
type string | Notification type |
data hash, optional | Notification data. You can also use resource key with other available data. For type: ping , data is an empty hash. |
user hash | Related user (useful when separating OAuth notifications) |
account hash | Related account |
delivery_attempts integer | Number of delivery attempts (excluded from webhook) |
delivery_response hash | Information about last delivery (excluded from webhook) |
created_at timestamp | |
updated_at timestamp | |
resource string, constant notification | |
resource_path string | |
subscriber hash | Separate different notification subsribers in list notifications endpoint |
Example notification for new payment to a bitcoin address (
wallet:addresses:new-payment
)
{
"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"
}
}
}
Example notification for completed buy (wallet:buys:completed)
{
"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
Scopes
wallet:notifications:read
Example request
curl https://api.coinbase.com/v2/notifications \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)
notifications = client.notifications
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)
notifications = client.get_notifications()
var Client = require('coinbase').Client;
var client = new Client({'apiKey': 'API KEY',
'apiSecret': 'API SECRET'});
client.getNotifications({}, function(err, notifications) {
console.log(notifications);
});
Example response
{
"pagination": {
"ending_before": null,
"starting_after": null,
"limit": 25,
"order": "desc",
"previous_uri": null,
"next_uri": null
},
"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,
"fees": [
{
"type": "coinbase",
"amount": {
"amount": "0.00",
"currency": "USD"
}
},
{
"type": "bank",
"amount": {
"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"
}
]
}
Show a Notification
Show a notification for which the current user was a subsciber.
HTTP Request
GET https://api.coinbase.com/v2/notifications/:notifications_id
Scopes
wallet:notifications:read
Example request
curl https://api.coinbase.com/v2/notifications/0fdfb26e-bd26-5e1c-b055-7b935e57fa33 \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)
notification = client.notification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)
notification = client.get_notification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')
var Client = require('coinbase').Client;
var client = new Client({'apiKey': 'API KEY',
'apiSecret': 'API SECRET'});
client.getNotification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33', function(err, notification) {
console.log(notification);
});
Example 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"
}
}