Deploying Your Webhook

You've written an awesome webhook. Now it's time to launch it!

Configure your Webhook Subscription


Select Account Settings from the user menu to access your webhook settings.

To activate webhooks on your account, visit the Routable Dashboard.

From the Sidebar on the left side of your Dashboard, click your name at the bottom to expand the user menu and select Account Settings. In the Account Settings section, find and select Webhooks in the left-hand Sidebar.

From this screen, you will see a dialog that will allow you to configure the URL that points to your code. You'll do this in the sandbox version of your Routable Dashboard to point to your staging or development environment, and in the production Dashboard to point to your production version once you're ready to release.


Create a new webhook subscription

Enter a subscription name, such as My Webhook, and the URL where your code can be called. You'll also need to create a secret key. This key will be used to sign webhook requests we send you, so you can be sure they came from Routable. We strongly recommend entering a complex key, such as the 504-bit WPA keys found at Click Add subscription to complete the subscription.

Testing Your Webhook

Once you've entered a URL to subscribe, Routable will run a series of tests against your webhook code and ensure that your code is properly processing both valid and invalid webhook requests. Don't worry if some of these fail; you'll have an opportunity to correct any failed tests. A list of conditions to validate against can be found on the Developing Webhooks page of this guide.

You'll see a dialog showing the result of our tests. It may take a moment to perform the full battery of tests. If any tests fail, you may correct your code and click Retry to re-attempt the tests. Once all tests are passing, click Continue to activate your webhook.


Validating a webhook...

Troubleshooting Tests

TestExpected StatusIf it fails...
Invalid timestamp - future401Validate that the Routable-Signature-Timestamp header is not in the future.
Invalid timestamp - past401Validate that the Routable-Signature-Timestamp header is not more than five minutes in the past.
Invalid company401Validate that the company_id in the request body we send matches your Routable company ID.
Invalid payload401Validate that the request body we send is valid JSON and return a 401 Unauthorized if it cannot be parsed.
Empty payload401Validate that the request body we send is not empty ({ }). Ideally, validate that it matches the expected payload structure.
Invalid signature401Check your signature verification algorithm and secret key.
Valid data200Validate that the request body we send matches the expected payload structure and return a 200 OK if it is.
Valid timestamp200Return a 200 OK if the Routable-Signature-Timestamp is between now and five minutes ago, and no other error conditions exist.

Once your webhook is activated, you will see it in the Valid state, and it will be able to receive requests generated by the Routable platform.

If you ever need to run these tests again, for example, if you have made changes to your webhook, click Test from the webhook subscription's context menu.


Option to re-run webhook tests.

Monitoring your Webhook

Once your webhook is fully configured, you'll be able to see its status at the top of the screen, and a history of requests we sent to your webhook (and the results of those requests.)

Your webhook status will be one of the following:

  • Pending webhooks are undergoing testing. You should only see webhooks in this status for a few moments.
  • Invalid webhooks are returning errors that Routable considers permanent errors, including any 4xx error and 500 Server Error. (Note that 401 Unauthorized should be returned by your webhook if request validation fails, and this condition will be tested for when validating a webhook.) Invalid webhooks will not receive new requests from the Routable application.
  • Valid webhooks have passed the validation tests and are active and ready to receive requests from the Routable application.

Your webhook can also be Paused. A paused webhook will not receive incoming requests, however, these requests will remain in a queue to be sent once you un-pause the webhook.

You can open any request to see the detailed body we sent.


An active webhook page


Using AWS Lambda or another serverless technology?

By default, Routable times out webhook requests after one second. (This means you should do any heavy lifting logic in a queue rather than in the webhook response itself.) However, AWS Lambda and other similar technologies have a "cold start" period when an endpoint has not been hit in a little while, and sometimes the cold start can exceed the one second threshold. If you're using one of these technologies, please inform the Developer Experience and Sales Engineering teams during your onboarding, and we will adjust your timeout window to allow sufficient time for your serverless solution to warm up and become ready to accept requests.

Disabling Your Webhook

If you ever wish to stop receiving webhook requests, open the webhook context menu and select Delete to remove the subscription.


Delete your webhook subscription if you no longer need it.