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.
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 randomkeygen.com. Click
Add subscription to complete the subscription.
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.
|Test||Expected Status||If it fails...|
|Invalid timestamp - future||401||Validate that the |
|Invalid timestamp - past||401||Validate that the |
|Invalid company||401||Validate that the |
|Invalid payload||401||Validate that the request body we send is valid JSON and return a |
|Empty payload||401||Validate that the request body we send is not empty (|
|Invalid signature||401||Check your signature verification algorithm and secret key.|
|Valid data||200||Validate that the request body we send matches the expected payload structure and return a |
|Valid timestamp||200||Return a |
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.
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:
Pendingwebhooks are undergoing testing. You should only see webhooks in this status for a few moments.
Invalidwebhooks are returning errors that Routable considers permanent errors, including any
500 Server Error. (Note that
401 Unauthorizedshould 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.
Validwebhooks have passed the validation tests and are active and ready to receive requests from the Routable application.
Your webhook can also be
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.
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.
If you ever wish to stop receiving webhook requests, open the webhook context menu and select
Delete to remove the subscription.
Updated 22 days ago