Notifications

Writing software against the blockchain and financial systems can be challenging, because actions are often performed asynchronously. Anyone who has implemented functionality for incoming bitcoin transactions is more than familiar with this. Polling APIs is easy to implement but hard to scale.

Today we’re thrilled to announce a new addition to Coinbase API family: Notifications. Notifications are alerts sent to your application using webhooks (POST request with JSON data) when corresponding actions are performed or observed by Coinbase. This makes it very easy to react to actions related to your application. We’re starting with a handful of important and heavily requested actions and will add more over time. Starting today you can subscribe to events such as these:

  • New transactions for bitcoin addresses created for your Coinbase wallets
  • Completion of your bitcoin buy or sell
  • Receipt of a successful payment for your merchant checkout order

API Notifications are built in similar way to our old callback system, which was mainly designed for merchant services. Our new notifications can be set up for both API keys and Coinbase Connect (OAuth2) applications. This makes it easy to subscribe to both your own and your application’s users’ notifications.

You can set the notification endpoint in your API settings individually for API keys and applications. Once you have subscribed to events and set the appropriate permissions to receive respective notifications, we’ll start sending them to your application. Each notification contains a unique ID, type, and the corresponding data payload:

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

We’re also now including user and account information for apps that are using Notifications for their Coinbase Connect applications, which enables you to differentiate notifications by unique user. If you’d like, you can access all your notifications via the API endpoint for notifications.

If you’re using merchant checkout products, you don’t necessarily need to set up API keys for simple payment integrations. Instead, you can set the notification endpoint in your merchant settings. Read more about merchant notifications.

As with all our APIs, we’re constantly listening to developer feedback and improving our offering. If there are Notification events you’d like for us to consider building, we would love to hear from you. Please send us feedback in either our Community Forum or email us at api@coinbase.com.

Please note: We’re hiring engineers (both in our San Francisco office and remote anywhere in the world). If you’re interested in speaking with us about a role we’ve set up a coding challenge that you can take in about 30–45 minutes. You can also apply through our careers site if you prefer to start the conversation that way.

Written by Jori Lallo