{"_id":"55fdb2a956d6990d00a6caca","category":{"_id":"55fdb08c4bebdf17004130d4","project":"556cd8aec14029190092d292","version":"556cd8aec14029190092d295","__v":11,"pages":["55fdb124b652110d00758b70","55fdb2a956d6990d00a6caca","55fdb38856d6990d00a6cacc","55ff6c519e7ccf0d000a1d7f","5613db97acd4343500088079","5616d7b9cf2a1e0d00247971","56196204fa2a6d0d002a1352","5622f2c906481c0d00e5315c","569526b8caa32519009c411e","569fbbcbbeb79a17009f8f89","56aac68aac665d0d00af76b0"],"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-19T18:59:24.105Z","from_sync":false,"order":4,"slug":"how-to","title":"How To..."},"parentDoc":null,"version":{"_id":"556cd8aec14029190092d295","__v":14,"project":"556cd8aec14029190092d292","createdAt":"2015-06-01T22:11:58.756Z","releaseDate":"2015-06-01T22:11:58.756Z","categories":["556cd8afc14029190092d296","55ca5a55241e790d004f47ea","55dc9fdb4f535537007da1b2","55dc9fdfc755b63700dc843c","55fdb08c4bebdf17004130d4","560ef4c2a36c610d00e7013e","5613db296a092921004c30c2","56156581dc8aea0d002475e8","56169d1ee98f5517005627a8","5622fde7de7dc01700c6dd5f","56cf75f3336aa60b0086a495","5818f3c02093901b00bcf91a","582f7ff88ea0800f0035639a","583f30c110448a2500dd990f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"556cbb50c14029190092d20f","__v":9,"project":"556cd8aec14029190092d292","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-19T19:08:25.007Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"If you want to receive updates when things at Reverb are changing, we have a webhook system that allows for this. This is a great way to build features based on when one of your listings is updated at Reverb, or when an order is created.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available Events\"\n}\n[/block]\nThe events we currently support are:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Webhook topic\",\n    \"h-1\": \"Oauth scope needed\",\n    \"0-0\": \"listings/update *\",\n    \"2-0\": \"orders/create\",\n    \"4-0\": \"payments/create\",\n    \"5-0\": \"payments/update\",\n    \"3-0\": \"orders/update\",\n    \"6-0\": \"app/uninstalled\",\n    \"0-1\": \"read_listings\",\n    \"2-1\": \"read_orders\",\n    \"3-1\": \"read_orders\",\n    \"4-1\": \"read_orders\",\n    \"5-1\": \"read_orders\",\n    \"1-0\": \"listings/publish\",\n    \"1-1\": \"read_listings\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n *only triggered on listing `state` and `inventory` changes.\n\nMore events may be added over time. If you are looking for a particular event, please ask [on our API forum](https://groups.google.com/forum/#!forum/reverb-api)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Security: ensuring webhook authenticity\"\n}\n[/block]\nWebhooks will eventually contain a header with an HMAC signature so that you can verify that it came from us. \n\nFor now, if you want to use webhooks and want to be sure that the post came from Reverb, register your webhooks at a secret url. For example, you may have a url such as `http://your.site.com/reverb_listing_update/a1b2c3` with a secret hash on the end. \n\nOnly Reverb will know this endpoint, so requests are less likely to be forged. Please keep in mind that this system is not foolproof, though if used correctly and the endpoint never exposed publicly, it is generally safe. A true signature-based security system is coming soon.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Webhook requirements\"\n}\n[/block]\nYour webhook endpoint should return a successful `200` status code _immediately_ upon receiving the webhook. It is recommended that any processing you do is done asynchronously. If your webhook takes too long to respond, Reverb may stop sending you webhook requests.\n\nTo ensure quick processing, use a queueing system. A simple way to do this is to write the webhook data to the database, and have a cron job that reads from the database and executes processing on your side. If you're using Ruby, look at [delayed job](https://github.com/collectiveidea/delayed_job) which works with your database, or [sidekiq](https://github.com/mperham/sidekiq) which is more robust but requires Redis.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Webhook Contents\"\n}\n[/block]\nWhen a webhook is posted, it will contain in its body, the standard json representation of the object in question. For example, a `listings/update` will render a listing object (same as fetching it from `/api/listings/[id]`), and an `orders/update` will render an order object.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Register to receive webhooks for your application\"\n}\n[/block]\nTo register for webhooks `POST` to `/webhooks/registrations`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XPOST https://api.reverb.com/api/webhooks/registrations --data '{\\\"url\\\": \\\"http://requestb.in/yourendpoint\\\", \\\"topic\\\": \\\"listings/update\\\"}' -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Content-Type: application/hal+json\\\" -H \\\"Accept: application/hal+json\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"View your registered webhooks for your application\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XGET https://api.reverb.com/api/webhooks/registrations -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Accept: application/hal+json\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"Deregister a webhook for your application\"\n}\n[/block]\nWhen you perform the `GET` request above, you will get a link to each webhook (via `_links.self.href`. Please use that link with the `DELETE` verb to remove the webhook.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XDELETE https://api.reverb.com/api/webhooks/registrations/[webhook_id] -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Accept: application/hal+json\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Testing your webhooks\"\n}\n[/block]\nYou must register webhooks for publicly accessible urls on the internet, so things like localhost will not work. If you want to test webhooks, one option is to register them with a service that captures such things, such as [RequestBin](http://requestb.in/). This service will allow you to capture the webhook body and inspect it.","excerpt":"How to get real-time updates to your app.","slug":"receive-updates-with-webhooks","type":"basic","title":"Receive updates with webhooks"}

Receive updates with webhooks

How to get real-time updates to your app.

If you want to receive updates when things at Reverb are changing, we have a webhook system that allows for this. This is a great way to build features based on when one of your listings is updated at Reverb, or when an order is created. [block:api-header] { "type": "basic", "title": "Available Events" } [/block] The events we currently support are: [block:parameters] { "data": { "h-0": "Webhook topic", "h-1": "Oauth scope needed", "0-0": "listings/update *", "2-0": "orders/create", "4-0": "payments/create", "5-0": "payments/update", "3-0": "orders/update", "6-0": "app/uninstalled", "0-1": "read_listings", "2-1": "read_orders", "3-1": "read_orders", "4-1": "read_orders", "5-1": "read_orders", "1-0": "listings/publish", "1-1": "read_listings" }, "cols": 2, "rows": 7 } [/block] *only triggered on listing `state` and `inventory` changes. More events may be added over time. If you are looking for a particular event, please ask [on our API forum](https://groups.google.com/forum/#!forum/reverb-api) [block:api-header] { "type": "basic", "title": "Security: ensuring webhook authenticity" } [/block] Webhooks will eventually contain a header with an HMAC signature so that you can verify that it came from us. For now, if you want to use webhooks and want to be sure that the post came from Reverb, register your webhooks at a secret url. For example, you may have a url such as `http://your.site.com/reverb_listing_update/a1b2c3` with a secret hash on the end. Only Reverb will know this endpoint, so requests are less likely to be forged. Please keep in mind that this system is not foolproof, though if used correctly and the endpoint never exposed publicly, it is generally safe. A true signature-based security system is coming soon. [block:api-header] { "type": "basic", "title": "Webhook requirements" } [/block] Your webhook endpoint should return a successful `200` status code _immediately_ upon receiving the webhook. It is recommended that any processing you do is done asynchronously. If your webhook takes too long to respond, Reverb may stop sending you webhook requests. To ensure quick processing, use a queueing system. A simple way to do this is to write the webhook data to the database, and have a cron job that reads from the database and executes processing on your side. If you're using Ruby, look at [delayed job](https://github.com/collectiveidea/delayed_job) which works with your database, or [sidekiq](https://github.com/mperham/sidekiq) which is more robust but requires Redis. [block:api-header] { "type": "basic", "title": "Webhook Contents" } [/block] When a webhook is posted, it will contain in its body, the standard json representation of the object in question. For example, a `listings/update` will render a listing object (same as fetching it from `/api/listings/[id]`), and an `orders/update` will render an order object. [block:api-header] { "type": "post", "title": "Register to receive webhooks for your application" } [/block] To register for webhooks `POST` to `/webhooks/registrations` [block:code] { "codes": [ { "code": "curl -XPOST https://api.reverb.com/api/webhooks/registrations --data '{\"url\": \"http://requestb.in/yourendpoint\", \"topic\": \"listings/update\"}' -H \"Authorization: Bearer [oauth_token]\" -H \"Content-Type: application/hal+json\" -H \"Accept: application/hal+json\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "get", "title": "View your registered webhooks for your application" } [/block] [block:code] { "codes": [ { "code": "curl -XGET https://api.reverb.com/api/webhooks/registrations -H \"Authorization: Bearer [oauth_token]\" -H \"Accept: application/hal+json\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "delete", "title": "Deregister a webhook for your application" } [/block] When you perform the `GET` request above, you will get a link to each webhook (via `_links.self.href`. Please use that link with the `DELETE` verb to remove the webhook. [block:code] { "codes": [ { "code": "curl -XDELETE https://api.reverb.com/api/webhooks/registrations/[webhook_id] -H \"Authorization: Bearer [oauth_token]\" -H \"Accept: application/hal+json\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Testing your webhooks" } [/block] You must register webhooks for publicly accessible urls on the internet, so things like localhost will not work. If you want to test webhooks, one option is to register them with a service that captures such things, such as [RequestBin](http://requestb.in/). This service will allow you to capture the webhook body and inspect it.