Webhooks in CustomerGate 365

Nothing leaves without a subscription

Webhooks are off until somebody creates a subscription in the Business Central client. There is no web service that can create or read a subscription: an address Business Central will call, and the secret it signs with, should not be something a website can set for itself.

How the receiving side verifies a signature, with test values to work it out without Business Central, is in the reference for website builders. This page stays with the two screens.

The events

One subscription per event; the same address may appear on several lines.

A counter visit reports Request Converted and not Order Created: every event has exactly one source, so a receiver never gets two names for one fact. A request marked as spam reports nothing. Neither does the cleanup job, which sets old requests to rejected while it erases their personal data: otherwise every night would bring a shower of messages about requests from a year ago.

Setting one up

1. Allow the app to make outgoing calls at all: on the Extension Management page choose CustomerGate 365, then Configure, and turn on Allow HttpClient Requests. Without it everything is neatly queued and nothing leaves.
2. On Webhook Subscriptions, create a line with a code, the https address and the event.
3. Choose Generate Secret and put the secret into the website straight away. It is shown once and cannot be read back anywhere afterwards, not in an export and not in a database copy.
4. Choose Enable. A subscription cannot be turned on without an address and a secret.
5. Choose Send Test Event. It goes out immediately and shows the status code that came back.
6. Set the delivery job to Ready. Like the mail job and the cleanup job it is created on hold; the Delivery Job action opens it.
7. Check on Webhook Deliveries that the test event shows as Delivered.

The subscription list warns at the top when outgoing HTTP is not allowed or when the delivery job is not set to Ready. Those are the two failures where everything looks fine and nothing leaves, so nobody goes looking for them. A new secret makes the old one stop working at once: until the website has the new one, it refuses every delivery.

The subscription list

Code, Description

The short name and one line on who is called here and why. The receiver sees the code in the X-VOA-Subscription header, so one endpoint can serve several subscriptions.

Endpoint URL

The address that is called with POST. It must start with https and must answer directly: a redirect is not followed with the signature headers.

Enabled

Whether this subscription is delivered. Disabling parks what was still queued for it; that is not sent later.

Secret

Present or Missing. The secret itself cannot be read anywhere. Remove Secret takes it away and turns the subscription off.

Consecutive Failures, Disabled After Failures

One successful delivery sets the counter back to zero. Reset Failures does it by hand, without changing anything else.

Last Attempt At, Last Status Code, Last Error

What happened at the last attempt. Status code zero means the address could not be reached at all.

Webhook Deliveries

Deliveries is the log: what was sent, what the endpoint answered and what is still waiting. Nothing here can be changed or removed.

State

Delivered, Waiting, or Parked after five attempts. Parked means the attempts are used up and the delivery job will not pick this row up again by itself.

Occurred At, Delivered At

When the event happened in Business Central, and when the endpoint accepted the delivery. Those are not the same moment.

Attempts, Last Status Code, Last Error, Next Attempt At

How often it was tried, what came back (the status code and the start of the answer) and when the job may try again.

Document Type, Document No., Customer No.

What the event is about, in the fixed tokens of the web service contract.

Show Payload

Shows the exact JSON that was sent, or will be sent. This is the body the signature is computed over, so it settles a disagreement about a signature in one go.

Retry Now

Puts this delivery back in the queue with a clean attempt counter. Use it after repairing the endpoint, or after outgoing HTTP has been allowed.

Deliver Now

Runs the delivery round immediately, for every delivery that is due.

Five attempts, and then it stops

• A delivery is attempted five times, with 1, 5, 30 and 120 minutes in between. After that it is parked and waits for a person.
• Anything other than a 2xx counts as a failure, and so does an endpoint that does not answer within ten seconds.
• After twenty failures in a row a subscription turns itself off. That number is on CustomerGate Setup.
• A subscription that turned itself off never comes back by itself. Repair the endpoint, choose Send Test Event and then Enable; parked deliveries come back with Retry Now.
• An environment that blocks outgoing HTTP does not count as a failure of the endpoint: that is a setting, not a broken receiver.
• A test event never counts towards any of this and works on a subscription that is switched off too.

A posting can never hang on it

An event that arises while something is being posted is written to the queue as a row inside that same transaction, and nothing else happens. The calling is done by the delivery job, every five minutes. A slow or broken endpoint can therefore never hold up a posting and never roll one back. If the posting itself is rolled back, the queued row goes with it.

Tell whoever builds the receiving side two things that follow from this: expect duplicates (a delivery that timed out on your side may well have arrived) and expect no fixed order (a retried event arrives after events that happened later).

What a message carries, and what it does not

A payload carries identifiers, states, amounts and dates, and no personal data: no name, no e-mail address, no phone number, no address and no free text. That is a rule of the app, not a habit of this version; a test fails as soon as one of those fields reaches a payload. If you need the name behind a request, ask Business Central for it with the number you got.

The two webhook tables therefore hold no personal data either, and neither the cleanup job nor erasure by e-mail address touches them. Delivered and parked rows disappear after the Webhook Log Retention period, thirty days by default: that is housekeeping, not a retention period. The secret lives in isolated storage and never in a table field, so it does not travel in an export or a database copy.

Webhooks belong to Complete

Webhooks are part of the Complete plan. With another plan nothing is queued and nothing is sent, whatever the subscriptions say; Webhook Subscriptions tells you so when it opens. During the trial they do work. See CustomerGate Licence.