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.

If your site is hosted on-premise, please follow the instructions in Installing Redis before attempting to use this feature.

Managing webhooks

Creating a webhook

creatingwebhooks.gif

  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.

Status Description
Sent The webhook message was sent and received an HTTP response code of 2xx from the endpoint.
Queued The message is queued for sending
Scheduled retry

The delivery attempt failed (received anything other than a 2xx response code), but is scheduled for a retry. Delivery retry intervals are as follows:

Immediate - first attempt

5m - 2nd attempt

30m - 3rd attempt

30m - 4th attempt

12h - 5th attempt

24h - last attempt

Failed All retry attempts have failed. NetX will mark the webhook as disabled; manual intervention is required to re-enable. Once a webhook message delivery has failed, it cannot be resent.

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.

failedallthewaydown.png

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

failedstates.png

  • 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

rediunavailable.png

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.

Was this article helpful?
0 out of 0 found this helpful