--- title: "Frameworks Webhooks - Implementation guides" canonical: "https://kb.myframeworks.com.au/space/FRAM/28391110/Frameworks%20Webhooks%20-%20Implementation%20guides" format: markdown --- This guide walks you through configuring a webhook in Frameworks so that a subscribed event automatically calls a URL you provide when it occurs. It covers configuring the subscription in **Event Definition Maintenance**, testing the call, and monitoring the event queue after go-live. For background on what a webhook is and how it fits with the Frameworks Automated Notification system, see [Understanding Webhooks](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/1079214929). > 📝 **Who performs this:** A Frameworks System Administrator, working with your IT team or an integration partner who owns the receiving endpoint. > 📝 > 📝 **Prerequisites:** > 📝 > 📝 - The **ANA** feature code must be active on your Frameworks licence. Contact your DMSi account manager if it's not. > 📝 - If the webhook will be triggered by CDC events, the **CDC** feature code must also be active and CDC must be enabled for your environment (which includes DMSi installing the database triggers, not just enabling the feature code). See [Change Data Capture Control](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/1076527107) and [Understanding Change Data Capture (CDC) Events](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28381126). > 📝 - Your endpoint must be built, hosted and reachable before the webhook subscription can be tested. Frameworks calls a URL you provide; it does not integrate directly with third-party platforms such as ecommerce sites, CRMs or shipping providers. The endpoint is typically built by your IT team or an integration partner and must be able to accept a POST request with a JSON payload, and respond with a JSON payload indicating success or failure. > 📝 - Access to **Event Definition Maintenance** should be restricted to trusted administrative users. The screen allows configuration of the URLs Frameworks will call and the conditions under which it will call them, so it should be granted only to roles authorised to make integration and notification configuration changes. ## Implementation Sequence This guide walks you through the complete implementation in the correct order: 1. Confirm the Endpoint Is Ready 2. Subscribe to the Event and Configure the Webhook 3. Add Conditions and Custom Headers (Optional) 4. Test the Webhook 5. Monitor the Event Queue After Go-Live --- ## Confirm the Endpoint Is Ready Before configuring the subscription in Frameworks, confirm with your IT team or integration partner that the receiving endpoint is built, hosted and reachable from the Frameworks server. ### Configuration Steps 1. Confirm the endpoint's URL with the team responsible for it. This URL is what Frameworks will call when the event occurs. 2. Confirm the endpoint accepts a POST request with a JSON body. 3. Confirm the endpoint returns a JSON response containing `success` (true or false) and `message` (a string that Frameworks will record against the event). 4. Confirm any authentication requirements (for example, an API key or bearer token) that Frameworks will need to send as a header. ### Result The endpoint is ready to receive webhook calls, and the URL and any required headers are recorded for use in the next step. > ⚠️ ### Important Notes > ⚠️ > ⚠️ - The endpoint must be reachable from the Frameworks server. If your Frameworks environment is cloud-hosted (AWS), a `localhost` address on your own network will not work. The endpoint needs to be exposed on a publicly reachable URL, or on a network the Frameworks server can reach. > ⚠️ - The response format is fixed. Frameworks expects `{"success": true, "message": "..."}` or `{"success": false, "message": "..."}`. If the endpoint returns anything else, Frameworks marks the event in error. --- ## Subscribe to the Event and Configure the Webhook The webhook subscription is created in **Event Definition Maintenance**. Each subscription links an event to the API-Notification action and stores the URL Frameworks will call. ### Configuration Steps 1. Click the **Frameworks Menu** and navigate to **System Administration > Event Notifications > Setup & Administration > Event Definition Maintenance**. 2. Click **New** to create a new subscription, or select an existing event to add an additional action. 3. From the **Event ID** drop-down menu, select the event to subscribe to. 4. Enable the **Subscribed** checkbox against the **API-Notification** action. 5. In the **API URI** field, enter the URL confirmed in the previous step. 6. Click **Save** to store the subscription. ### Result The subscription is created. When the selected event next occurs, Frameworks will call the URL in the **API URI** field with the event details as a JSON payload. > ⚠️ ### Important Notes > ⚠️ > ⚠️ - CDC events (**cdcCustomer**, **cdcCustomerContact**, **cdcProduct**, **cdcBranchProduct**, **cdcProductPrice**, **cdcSupplier**) only appear in the **Event ID** drop-down when **CDC Triggers Enabled** is set on the **Change Data Capture Control** screen. If the CDC events aren't listed, see [Change Data Capture Control](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/1076527107). > ⚠️ - An event can have multiple subscribed actions. For example, the same event can call a webhook, send an email and create a task, each with its own conditions. --- ## Add Conditions and Custom Headers (Optional) Conditions restrict when the webhook is called based on the data in the event. Custom headers let the subscription send additional information with the POST call, such as an authentication token or a routing hint. ### Configuration Steps 1. In **Event Definition Maintenance**, open the subscription created in the previous step. 2. To add a condition, enter a condition statement in the **Conditions** field. Use the lookup button on the helper field to see which data fields are available for the selected event. For the full condition syntax, supported operators and worked examples, see [Event Definition Condition Logic](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/344948737). 3. To add custom headers, enter one or more `"key":"value"` pairs in the **Header** field, separated by commas. Data fields from the event can be substituted into header values using the same lookup helper. 4. Click **Save** to apply the changes. ### Result When the event next occurs, Frameworks evaluates the conditions. If they're met, the webhook call is made with the configured headers. If the conditions are not met, the call is skipped and the event is logged as processed. > ✅ See [Event Definition Condition Logic](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/344948737) for the full operator list, available entities and worked examples. > ⚠️ ### Important Notes > ⚠️ > ⚠️ - A common use of conditions is filtering out events triggered by a particular user or a particular branch. For example, if a batch import routine causes a large volume of `cdcProduct` events, a condition can exclude events made by that import user so the webhook only fires for genuine user changes. > ⚠️ - Data available for conditions and header substitution varies by event type. Use the lookup helper rather than guessing field names. > ⚠️ - Conditions use ABL logical expression syntax with entity and field references (for example, `order:orderTotalInc > 5000`). --- ## Test the Webhook Testing before go-live confirms that Frameworks can reach your endpoint, that the endpoint responds correctly, and that Frameworks records the event as completed. Test directly against your endpoint, ideally using a staging or non-production version of it so no downstream systems are affected by test data. ### Configuration Steps 1. Confirm with your IT team or integration partner which endpoint URL to use for testing (typically a staging endpoint that mirrors production but doesn't push data on to your live downstream systems). 2. In **Event Definition Maintenance**, open the subscription to be tested. If the **API URI** is currently pointing at a production URL, change it to the test URL for the duration of testing. 3. Trigger the subscribed event in Frameworks. For example, updating a product's sell price in **Product Maintenance** will trigger **cdcProductPrice** if that subscription is being tested. 4. In **Notifications Event Queue** (**System Administration > Event Notifications > Setup & Administration > Notifications Event Queue**), find the resulting event and confirm it is marked as completed. If the event is in error, review the message returned by the endpoint to identify the cause. 5. With your IT team, confirm the receiving endpoint saw the call, the payload was in the expected shape, and any downstream processing worked correctly. 6. Once testing is complete, change the **API URI** back to the production endpoint URL if it was changed for testing, and click **Save**. ### Result The webhook has been confirmed working end to end: Frameworks fires the event, calls your endpoint, receives a success response, and marks the event as completed. > ⚠️ ### Important Notes > ⚠️ > ⚠️ - Test against a staging endpoint where possible, especially if your production endpoint pushes data on to live systems such as ecommerce sites or shipping providers. Firing test events against a production endpoint can create real downstream side effects. > ⚠️ - If your endpoint is not yet ready but the subscription needs to be validated, coordinate with your IT team to spin up a simple test receiver — a service that accepts the POST, returns `{"success": true, "message": "test received"}`, and logs the payload. This confirms the Frameworks side is configured correctly while the real endpoint is still under development. --- ## Monitor the Event Queue After Go-Live Once the webhook is live, the **Notifications Event Queue** shows the outcome of each webhook call. Regular monitoring is important because Frameworks does not automatically retry failed webhook calls — a failed call sits in the event queue until someone reviews it and takes action. ### Configuration Steps 1. Click the **Frameworks Menu** and navigate to **System Administration > Event Notifications > Setup & Administration > Notifications Event Queue**. 2. Filter or sort the queue by event type or by status to find webhook events. 3. Review any events in an error state and check the message returned by the endpoint to identify the cause. 4. Once the underlying issue is resolved (endpoint back online, authentication corrected, etc.), work with your IT team to decide whether missed events need to be replayed from source or whether the downstream system will pick up the current state on its next sync. ### Result Webhook activity is visible, endpoint problems can be identified and addressed, and failed events are not left silently unactioned. > ⚠️ ### Important Notes > ⚠️ > ⚠️ - Frameworks does not automatically retry a failed webhook call. If the endpoint was offline, returned an unexpected response format, or failed authentication, the event is marked in error in a single pass and your receiving system will not see the update unless someone intervenes. Regular queue monitoring is essential if you're relying on webhook-driven synchronisation. > ⚠️ - Repeated failures typically indicate a problem with your endpoint rather than with Frameworks. Investigate the endpoint (is it reachable, is authentication current, is it returning the expected JSON response) before adjusting the subscription. > ✅ ## Related Information > ✅ > ✅ - [Understanding Webhooks](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/1079214929) > ✅ - [Understanding Change Data Capture (CDC) Events](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28381126) > ✅ - [Change Data Capture Control](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/1076527107) > ✅ - [Secure API's](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28381040) > ✅ - [Postman API Documentation](https://documenter.getpostman.com/view/873359/Uyxkijs6) — Technical reference for the Frameworks Integration Platform APIs, including example webhook payload shapes.