Webhooks

Webhooks are used to send automated, real-time messages to external applications. When an event occurs in NetX, such as an asset upload, a webhook sends information about the new asset to a remote server's endpoint URL. Unlike the NetX API, which pulls data on demand, webhooks automatically push data to your system as soon as a system event is triggered, without manual intervention or additional code on the receiver's end.

Managing webhooks

Creating a webhook

1. Log on to NetX as an administrator, and navigate to System > Integrations > API > Webhooks.
2. Use Add webhook button to create a new webhook.
3. Enter a descriptive name for your webhook. This name will only be displayed in the webhooks table.
4. In the Endpoint URL field, enter the address where the webhook messages will be sent. HTTPS is required for all endpoints. If the URL contains one or more special characters, it must be percent-encoded.
5. Make sure the asset.create event is selected.
6. If your endpoint is ready and listening for messages, and you'd like to enable the webhook, leave the Enable box checked.
7. Click the Create button to continue. You will be prompted with a Secret, this is an optional security token that you can use to verify that NetX is the sender. If you'd like to use the secret, copy it and store it safely; it will not be shown again.
8. If you like, you can use the Test button to send a test payload to the endpoint.
9. Click Done to finish creating the webhook.

Editing a webhook

To edit or delete a webhook, click the webhook's row in the table, or click the action menu on the row and select Edit or Delete.

Disabling a webhook

If you'd prefer to temporarily disable the webhook, use the Status toggle shown on the Webhooks page or edit the webhook and uncheck the Enabled box.

Deleting a webhook

To delete a webhook, click the webhook's action menu and select Delete. You will be prompted to confirm the deletion.

Reset secret

If you'd like to generate a new secret, click the webhook's action menu and select Reset secret. You will be shown a new secret — make sure to copy and store in a safe place since it will not be shown again. Any applications that used the old secret will need to be updated with the new one.

Events

The following NetX events are available for use with webhooks:

asset.create - This event triggers a webhook request when a new asset is uploaded into NetX. Reimports and resyncs do not trigger this event.

Webhook delivery

Each time a webhook is triggered, NetX will send the event payload to the endpoint URL specified. The HTTP method used is POST. The content-type of the request is "application/json;  charset=utf-8".

Here is an example of the JSON request body:

{
  "event": {
    "assetId": 101,
    "systemEventType": "ASSET_CREATE",
    "eventId": "0c218a59-8d6c-4c20-b5fe-372f75162d13",
    "eventTime": 1674076946,
    "userId": 1
  },
  "token": "6od7VUynjVQbDgLUdzeNvc5KuRs",
  "messageTime": 1674076946,
  "messageId": "78480073-b8d2-4494-85a9-638f5a15e409",
  "subscriptionId": 201
}

Activity log

NetX keeps a log for each webhook of the last 30 days of events and delivery attempts. The following info is displayed in the log:

Event: The type of event that triggered the webhook

Created: The date and time that the webhook was triggered

Status: The status of the webhook message delivery. A list of statuses is shown below. To filter the log for certain statuses, use the Status filter in the top right corner.

Updated: The date and time that the status was last updated by the system.

Errors and troubleshooting

When NetX delivers a webhook request to the endpoint, it is considered successful if the endpoint replies with a 2xx status code within 10 seconds. If any other response code is received, or no response within 10 seconds, the webhook will be scheduled for a retry.

If multiple retry attempts fail, NetX will mark the webhook as disabled — this status will be shown in the UI via a red disabled status toggle, an error alert in the webhook details page, and a failed status in the activity log.

If a webhook is in failed status, it may indicate any of these scenarios:

• An invalid endpoint URL or typo
• A temporary network error that prevents NetX from connecting to the remote endpoint, or the endpoint from responding within 10 seconds
• The endpoint server is not accepting connections
• The endpoint is not configured to use HTTPS, or related certificate issues

Redis unavailable

The webhooks feature depends on the Redis database for message queueing. If your site cannot connect to Redis, or Redis is unavailable, you will see an alert on the Webhooks page, in addition to NetX log entries. If Redis is unavailable, you can still manage webhook endpoints but webhook messages will no longer be processed or sent.

If you are a SaaS customer, please contact Support for more assistance if you see this alert. If hosted on-premise, please verify that your Redis service is available.