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).

tip

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"
  }
}

Was this helpful?

Notification Resource​

List Notifications​

HTTP Request​

Scopes​

Show a Notification​

HTTP Request​

Scopes​

Notification Resource

List Notifications

HTTP Request

Scopes

Show a Notification

HTTP Request

Scopes