Webhooks eliminate the need to poll external systems in order to stay informed about changes. Instead, the external system proactively sends a notification to your webhook at the time an event occurs. This enables Nextworld to react to that event immediately.
For example, you can be notified anytime an item is purchased in another system, and populate a Nextworld table with that information.
Learn more in the following topics:
- Webhook configuration
Configure webhooks using the Credential Management , Event Definitions , Webhook Definitions and Webhook Setup applications.
- Credential Management application
Use the Credential Management application to create and manage credentials for external systems, such as HMAC keys for webhooks OAuth for MCP servers, or PGP encryption for data imports and exports.
- Webhook Definitions application
Use the Webhook Definitions application to select the authentication type and event definition for your webhook. Then, configure the data mappings from a webhook request into your event.
- Webhook Setup application
Use the Webhook Setup application to configure environment-specific information for a webhook definition, such as the secret, lifecycle, and run as user. You also use it to generate the URL that you reference in the external system configuration, and to activate your webhook.
- Webhook Log Inquiry application
Use the Webhook Log Inquiry application to view the webhook requests coming into the system. Each record shows either a successful or unsuccessful webhook event.
Webhook configuration
Configure webhooks using the Credential Management, Event Definitions, Webhook Definitions and Webhook Setup applications.
Credential Management application
If your webhook uses basic auth, go to the next step of configuration. If your webhook uses HMAC authentication type, in the Credentials Management application, you must:
- Create a new record and select HMAC for your credential type.
- Select your version, then select the Generate Secret field action.
- Copy your credential management record name. This is referenced in the webhook setup record.
If the external system gives you the HMAC secret in an encoded format, such as base64 or hex, enter it as provided in the same Credential Management record you would use for any other HMAC secret. The platform decodes it automatically when it verifies signatures.
Event Definitions application
You must configure an event definition that receives the data when a webhook request is received. Create an event definition of type User-Defined. On the Mapping page of your event definition, configure how to pass data into that event. Learn more in Event configuration.
Webhook Definitions application
In the Webhook Definitions application, you must create a new record and reference the name of your event definition. Then:
- On the General Configuration page, select your authentication type. Options include:
- HMAC (Shared Secret)—Create a secret key in the Credential Management application, then use the key in the Webhook Setup application and in the external system. The key authenticates each inbound request using the specified HMAC algorithm. In the Authentication section, complete the following:
- HMAC Signature HTTP Header—The HTTP header that holds the signature in each request. The header name varies by external system.
- Hashing Algorithm—The algorithm the external system uses to sign its requests. Select
SHA-1,SHA-256, orSHA-512. - Webhook Signature Logic Block—Optionally, a logic block for external systems that don't sign requests the standard way, such as Stripe, Slack, or Twilio. The logic block extracts the signed string and the signature or signatures from the request. The platform performs all hashing and comparison, and the shared secret is never available to the logic block.
- Basic Auth—Each inbound webhook request contains a username and password which is used to authenticate the request.
- Optionally, use the Duplicate Detection section on the General Configuration page to ignore requests that an external system sends more than once. Identify the unique event ID using:
- Message ID Header—The HTTP header that carries the event ID.
- Message ID Path in JSON Body—A JsonPath expression that locates the event ID in the request body, for external systems that only include it in the payload, such as Stripe.
- Optionally, if the external system expects a specific reply to each request, define the acknowledgement:
- Webhook Response Text—The text the webhook returns to the external system.
- Webhook Response Content Type—The content type of the reply, for external systems that expect a format other than JSON.
- HMAC (Shared Secret)—Create a secret key in the Credential Management application, then use the key in the Webhook Setup application and in the external system. The key authenticates each inbound request using the specified HMAC algorithm. In the Authentication section, complete the following:
- On the Mappings page, configure your data mappings. This can be manually done, or you can create advanced mappings with a logic block:
- Manual Mappings—Use the Data Mapper to manually map data from your request into your event definition. Select the request body or header and drag the arrow to the appropriate event payload. Select the line connecting the two data points to view or edit the properties.
- Logic Block—Optionally, you can do an advanced mapping by specifying a logic block of type Data Mapping. In that logic block, you must configure your mappings using Set Values actions. It should have one JSON Object data item as an input, and a record as the output with the table that the event definition payload is built over as the shape. Once you enter the logic block name, the input and output mappings are automatically populated in the subtables. Add the event payload key in the output mappings where you want to map the payload information.
Webhook Setup application
In the Webhook Setup application, you must:
- Create a new record and enter your webhook definition name.
- If your webhook definition uses HMAC authentication, enter the name of your credential management record.
- Optionally, select the run as user and lifecycle.
- Optionally, select Log Auth Failures to capture requests that fail authentication in the Webhook Log Inquiry application. Capture turns itself off after 24 hours.
- Save the record. This populates the URL which you reference in the external system.
Webhook Log Inquiry application
In the Webhook Log Inquiry application, you can view records for unsuccessful webhook requests. By default, only unsuccessful events are shown, but you can enable logging for successful events in the Webhook Setup record for the webhook definition.
To resolve an errored webhook, open the log record and review the error message. If your webhook was built with a data mapping logic block, you can debug the logic block to try and solve the problem. Once you have fixed the issue, use the Replay Request row action on the logging record to initiate the event again.
Open a record to see the webhook setup and definition record names, the timestamp, host, and the audit information for the request content such as the source IP address and request body.
If Log Auth Failures is selected in the Webhook Setup record, requests that fail authentication also appear here, with credentials removed. Use them to see why a signature check is failing, or to read a one-time verification token that an external system sends when you register a webhook.
Webhook Definitions application
Use the Webhook Definitions application to select the authentication type and event definition for your webhook. Then, configure the data mappings from a webhook request into your event.
General Configuration page
Select the authentication type for your webhook. Options include:
- HMAC—Create a secret key in the Credential Management application, then use the key in the Webhook Setup application and in the external system. The key authenticates each inbound request using the specified HMAC algorithm.
- Basic Auth—Each inbound webhook request contains a username and password which is used to authenticate the request.
HMAC is the industry standard and requires a HTTP Header that your hashed secret value is stored in, and a hashing algorithm.
Mappings page
Use the visual data mapper to manually map data from your request into your event definition.
Optionally, you can do an advanced mapping by specifying a logic block of type . In that logic block, you must configure your mappings using Set Values actions. It should have one or more records as the outputs with the table(s) that the event definition payload is built over as the shape(s) Once you enter the logic block name, the input and output mappings are automatically populated in the subtables. Add the event payload key in the output mappings where you want to map the payload information.
Webhook Setup
View a read-only inline version of the Webhook Setup application. This shows all of the places where the webhook definition is active in your current environment. Select the Create action to navigate to the application where you can create new setup records.
Webhook Setup application
Use the Webhook Setup application to configure environment-specific information for a webhook definition, such as the secret, lifecycle, and run as user. You also use it to generate the URL that you reference in the external system configuration, and to activate your webhook.
Specify the webhook definition you want to configure. Then, save the record to populate an endpoint URL. The external system makes requests to this endpoint.
If the webhook definition uses an HMAC authentication type, enter the name of your credential management record.
Optionally, select a run in lifecycle. If none is selected, base is used by default.
Optionally, select the Log Successful Requests checkbox to enable logging of successful webhook calls. Logging errors is done by default. To view logs for your webhook, navigate to the Webhook Logging application. Learn more in Webhook Log Inquiry application.
Optionally, select the Log Auth Failures checkbox to capture requests that fail authentication in the Webhook Log Inquiry application, so you can diagnose a misconfigured integration. Capture is limited to 100 requests per hour and turns itself off after 24 hours. Credentials are removed from captured requests.
Webhook Log Inquiry application
Use the Webhook Log Inquiry application to view the webhook requests coming into the system. Each record shows either a successful or unsuccessful webhook event.
By default, only unsuccessful events are shown, but you can enable logging for successful events in the Webhook Setup record for the webhook definition. To resolve an errored webhook, open the log record and review the error message. If your webhook was built with a data mapping logic block, you can debug the logic block to try and solve the problem. Once you have fixed the issue, use the Replay Request row action on the logging record to initiate the event again.
Open a record to see the webhook setup and definition record names, the timestamp, host, and the audit information for the request content such as the source IP address and request body.
Requests that fail authentication are captured only when Log Auth Failures is selected in the Webhook Setup record. Use these records to see why a signature check is failing, or to read a one-time verification token that an external system sends when you register the webhook.