Sign in with Coinbase Notifications API

Table of Endpoints

Name	Method	Endpoint	Scope
List Notifications	GET	`/v2/notifications`	`wallet:addresses:new-payment`
Show Notification	GET	`/v2/notifications/:notifications_id`	`wallet: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 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

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

Shell
Ruby
Python
JavaScript

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);
});

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

Shell
Ruby
Python
JavaScript

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);
});

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?

Table of Endpoints​

Overview​

Supported Notification Types​

New Payment​

Scope​

Example Response​

Completed Buy​

Scope​

Example Response​

List Notifications​

HTTP Request​

Scope​

Examples​

Request​

Response​

Show Notification​

HTTP Request​

Scope​

Examples​

Request​

Response​

Table of Endpoints

Overview

Supported Notification Types

New Payment

Scope

Example Response

Completed Buy

Scope

Example Response

List Notifications

HTTP Request

Scope

Examples

Request

Response

Show Notification

HTTP Request

Scope

Examples

Request

Response