Simulating Dropbox webhook deliveries locally

Shortly after Dropbox launched its webhooks feature, developers frequently asked how they could build and test a webhook endpoint on their own machines before deploying to production. To address this, Dropbox engineer Steve Marx created dropbox_hook.py, a small command-line utility that sends fake webhook requests designed to mirror what the Dropbox platform itself delivers.

The tool is available as open source on GitHub at github.com/dropbox/dropbox_hook, where you can also file issues or submit pull requests.

Firing test requests at your endpoint

Dropbox webhooks begin with a verification request to confirm that your endpoint actually receives notifications. To rehearse this handshake, run:

dropbox_hook.py verify http://127.0.0.1/your-webhook-url

Once your endpoint responds appropriately, you'll want to see a real notification payload. The tool handles that too:

dropbox_hook.py notify http://127.0.0.1/your-webhook-url --secret abc123xyz --user 12345678

Choosing the right parameters

  • --secret expects your Dropbox app secret. This is needed so the tool can correctly compute the signature that would normally accompany a live notification.
  • --user expects a numeric Dropbox user ID. In your production implementation, you obtain this ID during the OAuth flow or by calling the /account/info endpoint.