Webhooks

General

The Webhooks tab in the User Account or Team Account Settings of a PolySwarm UI Account allows you to manage webhooks used by your Account. In a Team Account, a User must have the Team Admin or Microengine Admin role to view and use the Webhooks tab.

HMAC Secret

The Webhook’s HMAC Secret is used to allow the remote web service to verify that the webhook call was made by the PolySwarm Marketplace. All Webhook calls are signed using the HMAC Secret, and can thus be verified by the recipient. In the Webhooks tab, the HMAC Secret is hidden by default. You can click the “Eye” icon to view it or click the “Copy” icon to copy it to your clipboard.

Rate Limit

The rate limit is the number of webhook messages your Webhook URL can process in one day (24hr period). This is the mechanism that you can use to control how many bounties your Engine receives in a day.

Status

A Webhook’s Status will be in one of the following states:

• Pending - The Webhook has been created, but has not been tested.
• Verified - The Webhook has been tested and the remote service responded correctly.
• Failed - The Webhook was Verified, but the remote service is no longer responding. If a Webhook is in the Failed state, it needs to be Tested again to become Verified.

URL

The Webhook URL must be the full URI that your web server is listening on to receive a webhook. It must use HTTPS. Often it will be something like: “https://example.com:1234/my/api/”

Creating

To create your first webhook, click the “Create webhook” button to open the webhook creation window. If you have one or more existing webhooks, you can click the “+” button to create another one.

In the Create Webhook window, enter the Webhook URL and its Rate Limit. Then click Save.

Deleting

To delete a webhook, click the “Trash” icon in the Actions column.

A webhook cannot be deleted if it is associated with an Engine. You need to remove the Webhook association from the Engine, and then you can delete the webhook.

Testing

In the Actions column, you can click on the “Gear” icon to open the Webhook Test window. Click the “Test” button to send a “Ping” action to the remote webhook server. Give it about one minute to send the webhook. If the webhook server responds to the Ping action, the Status will update to be “verified”.