InnerWeb
Skip to main content

Webhook and API integration acceptance checklist for a plant

The acceptance of a webhook and API integration should rest on one checklist, which the integrator and the IT manager tick off together during the pilot. Below are twelve points: the delivery mode, the limits of the outbox, delivery confirmations, the machine token and response codes. Each point has a comment on how to tell that it is met.

89
entries in one poller batch
Source: feature card
300 s
time an entry is reserved before it returns to the pool
Source: feature card

Why acceptance of an integration needs a list

A webhook integration works at the junction of two systems and two teams, so it is easy for each side to assume that the other has checked a critical element. A checklist forces every point to have an owner and evidence.

During the pilot the cost of a mistake is lowest: traffic is small and the team watches the results closely. Acceptance after the pilot lets you move to deployment knowing which limitations are acceptable and which require a fix.

Delivery mode and its limitations

The first decision concerns the delivery mode. The webhook:delivery_mode setting has two values: direct, the default, and outbox. Any value other than outbox means direct, so a typo in the setting silently enables direct mode. Check the value in the panel and record it in the protocol.

Outbox mode stores the webhook content in a table, and an external poller collects the entries and sends them on with the same payload. It was created for installations in which the network blocks outgoing traffic from the application host. It does, however, have limitations that the acceptance must take into account.

Limitations to accept or work around

Outbox has no retry limit, no spacing between retries and no alert for stuck entries. There is also no task that cleans up the table, so finished entries grow without end. A failed delivery confirmation returns the entry to the pending state and increases the attempt counter, so the poller retries it without end.

Acceptance should document who on the plant side monitors stuck entries and how the table grows. This is not a flaw to hide, but a known limitation that the organisation covers with a procedure.

Parameters of outbox acceptance

Parameters of outbox acceptanceChart: a poller batch of 89 entries, a reservation of 300 seconds, 6 reception event types.0100200300countEntries in a batch: 89 count89 countEntries in a batchReservation seconds: 300 count300 countReservation secondsReception event types: 6 count6 countReception event types
Source: Feature cards of the webhook outbox and of reception events

Confirmations and retries

Fetching pending entries atomically reserves a batch of up to 89 entries under a write lock in a transaction, so two pollers cannot collect the same entry. An entry in the delivering state whose reservation lasts longer than 300 seconds returns to the pool and may be collected again.

The delivery confirmation accepts the delivered or failed status with an optional error description, and it is idempotent: confirming an entry that has already been delivered changes nothing. Acceptance should include a test in which the poller sends the same confirmation twice and nothing changes.

API and the machine token

API calls require a machine token. Acceptance checks that the token is stored on the server side, not in browser code, and that a wrong or missing token gives a 401 response. For access requests, a 201 response means a new request, 200 a repeat of the same request identifier, and 400 incorrect data.

It is also worth checking that a repeated call with the same identifier does not create a duplicate. This is the most common fault in integrations that work in a test with a single call, but in production repeat the call when there is no response.

How to conduct the acceptance

The acceptance is conducted in one session with the integrator and the IT manager. Each point on the list ends with evidence: a screenshot of a setting, an entry in the channel, or a response with a code. A point without evidence counts as not met.

Points that are not met go onto a short list of corrections with a deadline, and the acceptance is considered complete once they are closed. The list, together with the evidence, becomes part of the integration documentation and is used during an audit.

Checklist

Video

Frequently asked questions

When should the integration acceptance take place?

At the end of the pilot, when traffic is real and the team still has time for corrections without production pressure.

Does outbox guarantee that an entry is never lost?

The entry stays in the table until it is confirmed, but there is no retry limit and no alert for stuck entries. That is why the acceptance requires a monitoring procedure.

Can a confirmation be sent more than once?

Yes. Confirming an entry that has already been delivered is idempotent and changes nothing.

Carry out the acceptance with our team

We will prepare an acceptance protocol for the integrator and the IT department based on this list. Book a meeting with InnerWeb.

Let's talk