Skip to main content

Create or Update a WebHook

The Save WebHook API registers a WebHook, or replaces the configuration of one that already exists. The same PUT serves both cases: if the hookId in the URL is already known to the server the stored record is replaced, and if it is not, a new record is created.

This is the canonical reference for the WebHookInfoItem schema. The Get All WebHooks, Get a WebHook by ID and Create a New WebHook Template calls all return the same object.

A save is a full replace, not a patch

Any field you leave out of the body is written with its default value, not with whatever was stored before. To change one setting on an existing hook, read it first with Get a WebHook by ID, change the field you care about, and send the whole object back.

API Endpoint​

  • HTTP Method: PUT
  • Endpoint: /api/v1/settings/web-hooks/{hookId}
  • Private Server Base URL: https://10.0.0.123:5022
  • Cloud Server Base URL: https://customername.econnectcloud.com/eventsbridge

Authentication​

This API call requires authentication with a JWT token, which must be passed in the header of the request.

Path Parameter​

  • hookId: The unique ID of the WebHook to create or update, in GUID/UUID format. It must not be the empty GUID. Generate one yourself, or take one from Create a New WebHook Template.

Request Body​

The body is a WebHookInfoItem. Only webHookName, hookId and hookOwnerUserName are marked required by the schema, but a hook that omits postbackAddress, or that leaves both event-family flags off, will never deliver anything.

Code Examples​

using eConnect.EventsBridge.Sdk;
using eConnect.EventsBridge.Sdk.Client;

// Assuming sdk is already initialized with authentication

// Use the HookId you persisted earlier, or call WebHooksCreateNewAsync() for a fresh one.
var hookId = Guid.Parse("e1bce9b4-5589-4d6e-b765-8f446a8a5c10");

var webHook = new WebHookInfoItem
{
    HookId = hookId,
    WebHookName = "PartnerServer1",
    PostbackAddress = "https://myserver.com/webhook/callback",

    // Disabled defaults to false on a hand-built item, but the /new template
    // returns Disabled = true. Always set it explicitly so the intent is clear.
    Disabled = false,

    // Pick at least one event family, or this hook receives nothing.
    WebHookFaceRec = true,
    WebHookLpr = false,

    FilterRules = PostbackEventFilters.SpecificTags,
    SpecificTags = new[] { "VIP", "Employee" },

    // Optional basic auth. Send the plain text here; the server encrypts it on save.
    AuthBasicUserName = "user123",
    AuthBasicPasswordDecrypted = "password123",

    // Optional static header, for example a bearer token your endpoint expects.
    HeaderKey = "Authorization",
    HeaderValue = "Bearer xxx.yyy.zzz",

    ServerPermitSelfSignedCerts = true,

    // Delivery behaviour. Resilient queues the payload and retries;
    // MaxRetryAttempts = 0 is fire-and-forget regardless of Resilient.
    Resilient = true,
    MaxRetryAttempts = 60,
    RetryIntervalMs = 1000,
    UseExponentialBackoff = false
};

await sdk.WebHookSaveAsync(hookId, webHook);

Raw Sample​

Here's an example of how to use the PUT method to save a WebHook:

Request​

PUT https://10.0.0.123:5022/api/v1/settings/web-hooks/e1bce9b4-5589-4d6e-b765-8f446a8a5c10
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
{
  "hookId": "e1bce9b4-5589-4d6e-b765-8f446a8a5c10",
  "webHookName": "PartnerServer1",
  "postbackAddress": "https://myserver.com/webhook/callback",
  "disabled": false,
  "webHookFaceRec": true,
  "webHookLpr": false,
  "filterRules": "SpecificTags",
  "specificTags": ["VIP", "Employee"],
  "authBasicUserName": "user123",
  "authBasicPasswordDecrypted": "password123",
  "headerKey": "Authorization",
  "headerValue": "Bearer xxx.yyy.zzz",
  "serverPermitSelfSignedCerts": true,
  "resilient": true,
  "maxRetryAttempts": 60,
  "retryIntervalMs": 1000,
  "useExponentialBackoff": false
}

Response​

  • 200 OK: The WebHook was saved. The response has no body.
  • 400 Bad Request: The body was missing or could not be parsed.
  • 401 Unauthorized: Missing or invalid JWT token.
  • 500 Internal Server Error: An issue occurred on the server side.

Field Descriptions​

Identity​

  • hookId (String, required): The GUID/UUID of this WebHook. The server always uses the value from the URL, so a mismatched hookId in the body is overwritten rather than rejected.
  • webHookName (String, required): A descriptive name for the WebHook, for example "PartnerServer1". This is what appears in the Events Bridge UI.
  • hookOwnerUserName (String, required): The account that owns the hook. For non-administrator callers the server overwrites this with your own username on every save, so you cannot assign a hook to another account. Administrators may set it freely.

Delivery target​

  • postbackAddress (String): The full URL that detection events are posted to, including protocol, hostname and path. For example https://myserver.com/webhook/callback.
  • disabled (Boolean): When true the hook is stored but delivers nothing. Use this to pause a hook without deleting it and losing the hookId.
  • serverPermitSelfSignedCerts (Boolean): When true, Events Bridge accepts a self-signed TLS certificate from your receiver. Defaults to true.

Event selection​

  • webHookFaceRec (Boolean): Deliver face detection events (WebHookFaceRecPayload) to this hook.
  • webHookLpr (Boolean): Deliver license plate events (WebHookLprPayload) to this hook.
  • filterRules (String): Which detections qualify for delivery. Sent as the name, not a number:
    • "Expected" — only events for subjects this account enrolled. This is the default.
    • "AnyTagged" — any tagged subject, including tags belonging to other accounts.
    • "SpecificTags" — only subjects carrying one of the tags in specificTags.
    • "AnyTaggedExceptExcluded" — any tagged subject except those carrying a tag in specificTags.
    • "All" — every event.
  • specificTags (Array of Strings): The tag list used by "SpecificTags" and "AnyTaggedExceptExcluded". Ignored by the other filter rules.

Receiver authentication​

  • authBasicUserName (String): Username for HTTP Basic authentication against your receiver. Leave empty to disable Basic auth.
  • authBasicPasswordDecrypted (String): The Basic auth password in plain text. Set this only when you want to change the password. The server encrypts it on save, stores the result in authBasicPasswordEncrypted, and clears this field.
  • authBasicPasswordEncrypted (String): The stored, encrypted password. This is a read-back value — see the caution below.
  • headerKey / headerValue (String): An optional static HTTP header added to every postback, most often Authorization with a bearer token your receiver validates.

Retry behaviour​

  • resilient (Boolean): When true the payload is written to a local database before delivery and retried on failure, so events survive a receiver being offline or the Events Bridge service restarting. When false the payload is delivered once and dropped if it fails.
  • maxRetryAttempts (Integer): How many times a failed delivery is retried. 0 is fire-and-forget — no retries, regardless of resilient.
  • retryIntervalMs (Integer): The base delay between attempts in milliseconds, in the range 300–60000. With useExponentialBackoff off, this is the fixed interval.
  • useExponentialBackoff (Boolean): When true the delay grows after each failed attempt, capped at five minutes, instead of staying at retryIntervalMs.

Additional Notes​

Preserve authBasicPasswordEncrypted on read-modify-write

Read responses return the Basic auth password only in its encrypted form, as authBasicPasswordEncrypted — never in plain text. If you GET a WebHook, change a field and PUT it back, send that value back unchanged: dropping it clears the stored credential. To set a new password, put the plain text in authBasicPasswordDecrypted instead and the server encrypts it on save.

  • Persist the hookId. Without it, your next "update" registers a second hook and the first one keeps delivering.
  • Enable at least one event family. webHookFaceRec and webHookLpr both default to false. A hook saved without either flag is stored, enabled and reachable, and still receives nothing.
  • Refresh short-lived tokens. If headerValue holds a JWT with a short expiry, re-save the WebHook on a schedule to keep it current. Events Bridge does not renew it for you.
  • Confirm the result with Send a Test Event rather than waiting for a real detection.
Last updated on by Travis Whidden