Skip to main content

Automating WebHook Setup

Events Bridge lets partners register and maintain their WebHooks entirely through the API, instead of clicking through the settings screen described in Manually Setting Up a WebHook. Automating this is strongly recommended: it removes transcription errors, and it lets you refresh short-lived credentials on a schedule.

This page is the end-to-end walkthrough. Each individual call has its own reference page under WebHook Management.

The Registration Lifecycle​

Step 1 — Get a hookId​

Every WebHook is addressed by a hookId in GUID/UUID form. You can generate one yourself, or call Create a New WebHook Template to have the server hand you one along with its current defaults.

Persist the hookId before you go any further. This is the single most common integration mistake: a script that requests a new template on every run registers a brand new WebHook each time it saves, and the abandoned ones keep delivering events to the same address. If you find yourself receiving duplicates, list your hooks with Get All WebHooks and clean up the strays.

Step 2 — Save the Configuration​

Send the completed WebHookInfoItem to Create or Update a WebHook. The same PUT creates and updates, so your setup code can run unconditionally.

A save is a full replace, not a patch — fields you omit are written with their defaults. To change one setting later, read the stored item with Get a WebHook by ID, modify it, and send the whole object back.

Three defaults will silently stop a hook from firing

The /new template is deliberately inert. Before your first save, make sure you have:

  1. Set disabled to false — the template returns true.
  2. Enabled webHookFaceRec, webHookLpr, or both — they default to false, and a hook with neither receives nothing.
  3. Set postbackAddress to your receiver URL.

None of these produce an error. The save succeeds, the hook appears in the UI, and no events ever arrive.

Step 3 — Test Before You Rely On It​

Call Send a Test Event to post a synthetic detection to your receiver and see exactly what it answered. This validates DNS, TLS, credentials and payload parsing in one round trip, and it works on a hook that is still disabled.

Note that a 200 OK from the test endpoint only means the attempt completed — read the success field for the actual outcome.

Step 4 — Keep It Current​

  • Rotating a bearer token: read the hook, replace headerValue, save it back. If it also uses Basic auth, send authBasicPasswordEncrypted back unchanged or the stored password is cleared.
  • Changing the Basic auth password: put the new plain-text value in authBasicPasswordDecrypted. The server encrypts it on save.
  • Pausing delivery: save with disabled: true rather than deleting, so you keep the hookId and the rest of the configuration.

Complete Example​

The following creates or reuses a hook, saves a full configuration, and verifies it — the whole lifecycle in one script.

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

// Assuming sdk is already initialized with authentication

// 1. Reuse the HookId you stored last time, or ask for a fresh template.
//    Calling /new every run creates a new hook on every save.
var hookId = LoadPersistedHookId();

if (hookId is null)
{
    var template = await sdk.WebHooksCreateNewAsync();
    hookId = template.HookId;
    PersistHookId(hookId.Value);
}

// 2. Describe the hook you want. A save is a full replace, not a patch.
var webHook = new WebHookInfoItem
{
    HookId = hookId.Value,
    WebHookName = "PartnerServer1",
    PostbackAddress = "https://myserver.com/webhook/callback",

    Disabled = false,           // the /new template returns true
    WebHookFaceRec = true,      // subscribe to at least one event family
    WebHookLpr = true,

    FilterRules = PostbackEventFilters.Expected,

    HeaderKey = "Authorization",
    HeaderValue = "Bearer xxx.yyy.zzz",
    ServerPermitSelfSignedCerts = false,

    Resilient = true,
    MaxRetryAttempts = 60,
    RetryIntervalMs = 1000,
    UseExponentialBackoff = false
};

await sdk.WebHookSaveAsync(hookId.Value, webHook);

// 3. Confirm the receiver actually accepts a payload before relying on it.
var test = await sdk.TestWebHookAsync(hookId.Value);
Console.WriteLine($"Test result: {test.Success} ({test.StatusCode}) {test.Message}");

Delivery Guarantees​

How hard Events Bridge tries to deliver an event is governed by four fields, documented in full on the save page:

SettingEffect
resilient: false, maxRetryAttempts: 0Fire-and-forget. One attempt, dropped on failure. This is what /new returns.
resilient: trueThe payload is persisted locally first, so it survives a service restart as well as a receiver outage.
maxRetryAttemptsHow many times a failed delivery is retried. 0 disables retries even when resilient is true.
retryIntervalMs + useExponentialBackoffThe delay between attempts — fixed, or growing to a five minute cap.

Choose resilient when missing an event is worse than receiving it late.

Best Practices​

  1. Persist the hookId. Everything else follows from this.
  2. Set disabled and the event-family flags explicitly on every save, rather than relying on defaults.
  3. Run a test event as part of your deployment, and fail the deploy when success is false.
  4. Re-save on a schedule if your headerValue token is short-lived. Events Bridge does not renew it for you.
  5. Use valid certificates on public endpoints. serverPermitSelfSignedCerts exists for private networks; leaving it on for an internet-facing receiver removes a real protection.
  6. Acknowledge fast. The test endpoint times out at 10 seconds, and slow receivers cause retries on live traffic. Return 200 immediately and process the payload asynchronously.
Last updated on by Travis Whidden