Receive updates with webhooks
How to get real-time updates to your app.
This is for Advanced Users Only
Most users can sync inventory without the need of webhooks. Please note, there is not technical support specifically for webhooks. Because of this, if you encounter issues, support might be limited. Please tread cautiously.
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.
Available Events
The events we currently support are:
Webhook topic | Oauth scope needed |
---|---|
listings/update * | read_listings |
listings/publish | read_listings |
orders/create | read_orders |
orders/update | read_orders |
payments/create | read_orders |
payments/update | read_orders |
app/uninstalled |
*only triggered on listing state
and inventory
changes.
Security: ensuring webhook authenticity
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.
Webhook requirements
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 which works with your database, or sidekiq which is more robust but requires Redis.
Webhook Contents
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.
Register to receive webhooks for your application
To register for webhooks POST
to /webhooks/registrations
curl -XPOST https://api.reverb.com/api/webhooks/registrations --data '{"url": "http://requestbin.com/yourendpoint", "topic": "listings/update"}' -H "Authorization: Bearer [oauth_token]" -H "Content-Type: application/hal+json" -H "Accept: application/hal+json"
View your registered webhooks for your application
curl -XGET https://api.reverb.com/api/webhooks/registrations -H "Authorization: Bearer [oauth_token]" -H "Accept: application/hal+json"
Deregister a webhook for your application
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.
curl -XDELETE https://api.reverb.com/api/webhooks/registrations/[webhook_id] -H "Authorization: Bearer [oauth_token]" -H "Accept: application/hal+json"
Testing your webhooks
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. This service will allow you to capture the webhook body and inspect it.
Updated 11 months ago