Guides
DocumentationLog In

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 typeRequired permissionDescription
pingNonePing notification can be send at any time to verify that the notification URL is functioning
wallet:addresses:new-paymentwallet:addresses:readNew payment has been made to a Bitcoin 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:deposit:createdwallet:deposit:read or wallet:deposit:createA deposit has been created
wallet:deposit:completedwallet:deposit:read or wallet:deposit:createA deposit has been completed
wallet:deposit:canceledwallet:deposit:read or wallet:deposit:createA deposit has been canceled
wallet:withdrawal:createdwallet:withdrawal:read or wallet:withdrawal:createA withdrawal has been created
wallet:withdrawal:completedwallet:withdrawal:read or wallet:withdrawal:createA withdrawal has been completed
wallet:withdrawal:canceledwallet:withdrawal:read or wallet:withdrawal:createA withdrawal has been canceled
FieldsDescription
id stringResource ID
type stringNotification type
data hash, optionalNotification data. Related resource is available in resource key together with other available data. For type: ping the data will be 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 hashSubscribing object to 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"
  }
}