Receive updates with webhooks

📘

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:

*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.