Skip to main content

Auto Configure WebHook Settings

The Events Bridge allows partners to automatically configure WebHook settings to receive detection event notifications. This can be done using API calls that allow partners to manage their WebHooks programmatically. Each WebHook should have a unique hookId in GUID/UUID form, and partners can update or delete WebHooks based on this hookId.

It is highly recommended that partners utilize automated configuration to reduce human errors and streamline integration. Partners can also update their WebHooks periodically, especially if using a JWT token with a short expiration period.

General Instructions​

  • PUT a WebHook: The partner can post their desired WebHook configuration (including callback URL, JWT token, or any other authentication information). This process ensures the WebHook is set up programmatically, reducing manual configuration and errors.
  • Persist hookId: Partners should persist the hookId they receive or generate. This hookId will be required for future updates to avoid creating a new WebHook each time an update is made.
  • GUID/UUID for hookId: The hookId must be unique and should not be an empty GUID. Partners can generate their own hookId or call the /new endpoint to generate one.
  • Updating JWT Tokens: If the JWT token used for authentication has a short expiration period, partners can regularly update the WebHook configuration by posting an updated schema to the API.
  • Resilient Delivery (Optional): If the resilient flag is set to true, the system will persist the payload in a local database and continuously attempt to deliver the payload if the upstream service is offline. It will retry once per second until a 200 OK response is received from the server.

API Overview​

The WebHooks controller supports the following operations:

  • PUT: Create or update an existing WebHook.
  • GET: Retrieve details of a specific WebHook or all WebHooks.
  • DELETE: Remove a WebHook.

Add/Update Web Hook​

This endpoint allows partners to create or update an existing WebHook configuration. Partners should ensure they persist the hookId to avoid creating a new WebHook when updating existing configurations.

Code Examples​

using eConnect.EventsBridge.Sdk;

// Assuming sdk is already initialized with authentication
// Create a new WebHook configuration
var newWebHook = await sdk.WebHooksCreateNewAsync();

// Configure the WebHook
var webHookConfig = new WebHookInfoItem
{
    HookId = newWebHook.HookId,
    WebHookName = "MyWebHook",
    HookOwnerUserName = "admin_user",
    PostbackAddress = "https://your-webhook-endpoint.com",
    FilterRules = PostbackEventFilters.SpecificTags,
    SpecificTags = new List<string> { "VIP", "Alert" },
    WebHookFaceRec = true,
    WebHookLpr = true,
    Resilient = true,
    ServerPermitSelfSignedCerts = false
};

// Save the WebHook configuration
await sdk.WebHookSaveAsync(newWebHook.HookId, webHookConfig);

Raw Sample​

PUT https://10.0.0.123:5022/api/v1/settings/web-hooks/{hookId}
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body Example​

{
  "webHookName": "PartnerServer1",
  "postbackAddress": "https://myserver.com/webhook/callback",
  "allowSelfSignedCerts": true,
  "authBasicUserName": "user123",
  "authBasicPasswordDecrypted": "password123",
  "headerKey": "Authorization",
  "headerValue": "Bearer xxx.yyy.zzz",
  "filterRules": "Expected",
  "specificTags": ["VIP", "Employee"],
  "resilient": true
}

Request Parameters​

  • hookId: Unique ID of the WebHook to create or update (GUID/UUID format).

Field Descriptions​

  • webHookName: A descriptive name for the WebHook (e.g., "PartnerServer1").
  • postbackAddress: The full URL where the system will send detection events (including protocol, hostname, and path).
  • allowSelfSignedCerts: Whether to allow self-signed SSL certificates.
  • authBasicUserName and authBasicPasswordDecrypted: If basic authentication is required, provide credentials here.
  • headerKey and headerValue: Optional HTTP header (e.g., for JWT token authentication).
  • filterRules: Filters the events sent to the WebHook. Options include:
    • "Expected": Only send events with a valid external ID.
    • "AnyTagged": Send all tagged entities.
    • "SpecificTags": Send events for specific tags.
    • "AnyTaggedExceptExcluded": Sent Any Tagged Face, Except for those in the SpecificTags array.
    • "All": Send all events.
  • specificTags: An array of tags to filter by (only required if filterRules is set to "SpecificTags").
  • resilient: If set to true, the system will store the payload in a local database and keep retrying the postback once per second until a 200 OK is received from the server. This ensures that the payload is delivered even if the receiving server is temporarily offline.

Get Existing Web Hook​

Retrieve the details of a specific WebHook by its hookId.

Request​

GET https://10.0.0.123:5022/api/v1/settings/web-hooks/{hookId}
Authorization: Bearer <your_jwt_token>

Example Response​

{
  "webhookId": "e1bce9b4-5589-4d6e-b765-8f446a8a5c10",
  "webHookName": "PartnerServer1",
  "postbackAddress": "https://myserver.com/webhook/callback",
  "allowSelfSignedCerts": true,
  "authBasicUserName": "user123",
  "headerKey": "Authorization",
  "headerValue": "Bearer xxx.yyy.zzz",
  "filterRules": "Expected",
  "resilient": true
}

Get All Web Hooks​

Retrieve the details of all WebHooks configured for the user.

Request​

GET https://10.0.0.123:5022/api/v1/settings/web-hooks
Authorization: Bearer <your_jwt_token>

Example Response​

[
  {
    "webhookId": "e1bce9b4-5589-4d6e-b765-8f446a8a5c10",
    "webHookName": "PartnerServer1",
    "postbackAddress": "https://myserver.com/webhook/callback",
    "allowSelfSignedCerts": true,
    "authBasicUserName": "user123",
    "headerKey": "Authorization",
    "headerValue": "Bearer xxx.yyy.zzz",
    "filterRules": "Expected",
    "resilient": true
  },
  {
    "webhookId": "d3fce2a6-b7ed-4239-b985-c287a9f56421",
    "webHookName": "PartnerServer2",
    "postbackAddress": "https://another-server.com/webhook",
    "allowSelfSignedCerts": false,
    "authBasicUserName": "admin",
    "headerKey": "Authorization",
    "headerValue": "Bearer aaa.bbb.ccc",
    "filterRules": "All",
    "resilient": false
  }
]

Delete Web Hook​

This endpoint allows you to delete an existing WebHook by its hookId.

Request​

DELETE https://10.0.0.123:5022/api/v1/settings/web-hooks/{hookId}
Authorization: Bearer <your_jwt_token>

Request Parameters​

  • hookId: The unique ID of the WebHook to delete.

Best Practices​

  1. Persist the hookId: Ensure your system stores the hookId after creating or retrieving a WebHook for easier future updates or deletions.
  2. Use JWT Authentication: For added security, it's recommended to use JWT tokens in the header. Regularly update the token if it has a short expiration time.
  3. Self-Signed Certificates: The system can accept self-signed certificates for private networks, but it's recommended to use valid certificates for public-facing endpoints.
  4. Automate Configuration: Automating WebHook setup and updates reduces manual errors and ensures consistent integration with Events Bridge.
  5. Resilient WebHooks: If you expect occasional downtime for your server, use the resilient flag to ensure the system will keep retrying postbacks until a successful delivery.