Properly naming and configuring the path of your webhooks is a critical best practice to ensure your workflows are maintainable and easy to track.
Read the Introduction to Webhooks article for more information.
Why naming conventions matter
A webhook's path becomes part of the URL used for communication with external systems. Failing to configure a meaningful name can lead to tracking issues and unnecessary work, especially when the webhook URL is placed in third-party applications.
Consequences of poor naming:
Difficulty tracking: If a webhook is created and takes a nonsensical path based on a temporary story name (e.g.
new_story_for_user_7086), it becomes difficult to track where the URL leads.Inconvenience: If you later rename the story, or need to update the path, you must manually go to every third-party tool where that webhook URL is used and update it as well.
Best practices for webhook configuration
Use a meaningful path
The path you set for your webhook is part of the URL it generates. This path should be descriptive of the webhook's function.Example: Instead of a generic or temporary name, a webhook that receives support ticket updates could be named
support-notifications. This immediately informs you of the webhook's purpose when viewing the URL.
Name the action itself
Always name the webhook action within your story (e.g., do not leave it asWebhook Action).Use webhook rules
Webhook Rules allow you to specify criteria that must be met in order for an event to be emitted. Read more about webhook rules in our docs, here.Prioritize sensible configuration
Even if the webhook is used as the entry point for a send to story action, where the path is not relevant to the invocation, it is still considered good practice to configure a sensible path and name the action. This maintains a good habit, particularly for stories that may be invoked both via send to story and direct webhook calls.
Read more about webhooks in our docs, here.