Invoice Event Webhooks

The Webhook System

GoCoin sends webhook notifications to update your system of invoice related events, like payments. All webhooks for a particular invoice are sent to the "callback_url" parameter in invoice.

Events

The following events are monitored within GoCoin and can generate Webhooks:

Event Trigger
invoice_created Sent when an invoice is created
invoice_payment_received Payment is detected and unconfirmed on the network
invoice_ready_to_ship Payment(s) confirmed for the full amount of the invoice
invoice_merchant_review A Payment was received after the payment window, or the invoice expired while underpaid. Contact support to resolve.
invoice_invalid Invalid payments detected. Purchaser may be attempting to double spend Bitcoin. Contact support.

Webhook Contents

Webhooks are sent as HTTP POST requests to your URL with a json body (Content-Type: application/json) for easy parsing in almost any programming language. All Webhooks contain the following keys:

Key Description
id A unique, numeric, identifier for the webhook. You can use this value to record which webhooks you’ve already seen or recorded or acted on
event An identifier for the type of event that occurred. See Events, below
payload An object containing pertinent data about the event.

Examples of payloads for other event types is given in the section on Example Payloads.

Webhook body

{
  "id" : "<event id>",
  "event" : "<event>",
  "payload" : {
               "id": "84c4fc04-66f2-49a5-a12a-36baf7f9f450",
               "status": "unpaid",
               "payment_address": "1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
               "price": "1.00000000",
               "crypto_balance_due": "1.00000000",
               "price_currency": "BTC",
               "valid_bill_payment_currencies": null,
               "base_price": "134.00",
               "base_price_currency": "USD",
               "service_fee_rate": "0.01",
               "usd_spot_rate": "1.0",
               "spot_rate": "0.00746268656716",
               "inverse_spot_rate": "134.0",
               "crypto_payout_split": "100",
               "confirmations_required": 2,
               "crypto_url": null,
               "gateway_url": "https://gateway.gocoin.com/invoices/84c4fc04-66f2-49a5-a12a-36baf7f9f450",
               "notification_level": null,
               "redirect_url": "http://www.example.com/redirect",
               "order_id": null,
               "item_name": null,
               "item_sku": null,
               "item_description": null,
               "physical": null,
               "customer_name": null,
               "customer_address_1": null,
               "customer_address_2": null,
               "customer_city": null,
               "customer_region": null,
               "customer_country": null,
               "customer_postal_code": null,
               "customer_email": null,
               "customer_phone": null,
               "user_defined_1": null,
               "user_defined_2": null,
               "user_defined_3": null,
               "user_defined_4": null,
               "user_defined_5": null,
               "user_defined_6": null,
               "user_defined_7": null,
               "user_defined_8": null,
               "data": null,
               "expires_at": "2013-10-01T18:47:45.150Z",
               "created_at": "2013-10-01T18:32:45.153Z",
               "updated_at": "2013-10-01T18:32:45.153Z",
               "server_time": "2014-06-24T19:03:16Z",
               "callback_url": "https://www.example.com/gocoin/callback",
               "merchant_id": "63d3cd4c-1514-11e3-a3f0-080027fd9579"
              }

Webhook Acknowledgement and Automatic Retries

Upon receipt of a webhook, you should accept it by returning an HTTP “200 OK” response as quickly as possible. Sending any other response (i.e. “500 Internal Server Error”, “404 Not Found”, etc.) OR failing to return a response within approximately 30 seconds will result in automatic retries of the webhooks.

GoCoin will automatically retry the webhook twice, after which we can manually resend if necessary.

Verifying Authenticity

If you are concerned that an attacker might attempt to emulate a webhook to confirm their purchase, please consider the following.

  • A list of IP Addresses to whitelist is available on request. Please message support@gocoin.com for more information.
  • The GoCoin Hosted Gateway does not include the callback_url parameter in any of its views. If you do not either, that information is not easily accessible.
  • There are several fields available in the invoice that you can store data in when creating an invoice. Take a look at this article.