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](mailto:support@gocoin.com) to resolve.  |

| invoice_invalid | Invalid payments detected. Purchaser may be attempting to double spend Bitcoin. Contact [support](mailto:support@gocoin.com).          |  


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](mailto: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](http://help.gocoin.com/kb/setup-integration/verify-webhook-authenticity-create-a-signature).