GuidesAPI Reference
DocumentationLog In

Fields and security

Webhooks make it easier to integrate with Coinbase Commerce by allowing you to subscribe to a set of charge events. You can subscribe to the events by going to your settings page and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for. Below is the list of all available webhook events:

EventDescription
charge:createdNew charge is created
charge:confirmedCharge has been confirmed and the associated payment is completed
charge:failedCharge failed to complete
charge:delayedCharge received a payment after it had been expired
charge:pendingCharge has been detected but has not been confirmed yet
charge:resolvedCharge has been resolved

Example of a webhook payload

{
    "id": 1,
    "scheduled_for": "2017-01-31T20:50:02Z",
    "event": {
        "id": "24934862-d980-46cb-9402-43c81b0cdba6",
        "resource": "event",
        "type": "charge:created",
        "api_version": "2018-03-22",
        "created_at": "2017-01-31T20:49:02Z",
        "data": {
          "code": "66BEOV2A",
          "name": "The Sovereign Individual",
          "description": "Mastering the Transition to the Information Age",
          "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
          "created_at": "2017-01-31T20:49:02Z",
          "expires_at": "2017-01-31T21:49:02Z",
          "timeline": [
            {
              "time": "2017-01-31T20:49:02Z",
              "status": "NEW"
            }
          ],
          "metadata": {},
          "pricing_type": "no_price",
          "payments": [],
          "addresses": {
            "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
            "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
          }
        }
    }
}

Fields

FieldTypeDescription
idnumberDelivery attempt number
scheduled_fortimestampDelivery schedule time
eventhashCorresponding event object

Securing webhooks

Every Coinbase Commerce webhook request includes an X-CC-Webhook-Signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret from your settings page. Always make sure that you verify the webhook signature before acting on it inside your system. All integrations on our public github page verify this already, but if you need to implement it yourself please take a look at our reference ruby implementation.