Deploying Your Webhook
You've written an awesome webhook. Now it's time to launch it!
Configure your Webhook Subscription
![webhooks page.gif 1024](https://files.readme.io/210ea99-webhooks_page.gif)
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.
![webhook subscribe.jpg 522](https://files.readme.io/3ab92b7-webhook_subscribe.jpg)
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 randomkeygen.com. 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.
![Screen Shot 2022-02-10 at 11.53.52 AM.png 663](https://files.readme.io/f12d5b2-Screen_Shot_2022-02-10_at_11.53.52_AM.png)
Validating a webhook...
Troubleshooting Tests
Test | Expected Status | If it fails... |
---|---|---|
Invalid timestamp - future | 401 | Validate that the Routable-Signature-Timestamp header is not in the future. |
Invalid timestamp - past | 401 | Validate that the Routable-Signature-Timestamp header is not more than five minutes in the past. |
Invalid company | 401 | Validate that the company_id in the request body we send matches your Routable company ID. |
Invalid payload | 401 | Validate that the request body we send is valid JSON and return a 401 Unauthorized if it cannot be parsed. |
Empty payload | 401 | Validate that the request body we send is not empty ({ } ). Ideally, validate that it matches the expected payload structure. |
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 200 OK if it is. |
Valid timestamp | 200 | Return 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.
![webhook retest.jpg 1040](https://files.readme.io/9d83756-webhook_retest.jpg)
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 any4xx
error and500 Server Error
. (Note that401 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.
![webhook page.jpg 1754](https://files.readme.io/5dfd59a-webhook_page.jpg)
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.
![webhook delete.jpg 1040](https://files.readme.io/e896e91-webhook_delete.jpg)
Delete your webhook subscription if you no longer need it.
Updated over 1 year ago