When webhook deliveries fail
If your receiver stops accepting deliveries, wawa keeps retrying, warns your account's administrators, and only switches the endpoint off after about a week. You can recover the events from the last 30 days without any technical knowledge of the receiver. This page is for the administrator who gets the warning, and for the team that runs the receiver.
What wawa does
A delivery fails when the receiver answers with anything other than a 2xx, redirects, takes longer than 30 seconds, or can't be reached.
| Since the first failure | What happens |
|---|---|
| Straight away | wawa retries each delivery after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2, 4, 8 and 16 hours, then 1, 2 and 3 days: 13 attempts over about a week. |
| After an hour or so | On the first failed attempt at least an hour after the first failure, the account's administrators get an email and an in-app notice that the endpoint is failing. |
| About a week | Once five deliveries in a row have used up all their attempts, the endpoint switches itself off and shows as Auto-disabled. Deliveries still waiting are cancelled, no new ones are made, and the administrators are told again. |
| 30 days | Resend Events covers the last 30 days. Older deliveries stay in the log while an HTTP retry is pending, a successful handoff awaits its assigned client’s report, or a provider outcome is failed or unknown. |
A delivery that succeeds clears the failure count, so a receiver that recovers part-way through keeps the endpoint on.
If you're told an endpoint is failing
Fix the receiver, or ask the team that runs it to. Once it accepts deliveries again, wawa sends the deliveries still waiting for a retry by itself. A delivery that has used up all its attempts is not retried, so if any did while the endpoint stayed on, select Resend Events and choose a time before the oldest of them was sent. The endpoint's Deliveries tab lists them as Abandoned.
If an endpoint has been switched off
- Fix the receiver.
- In Settings → Connect → Webhooks, open the endpoint and select Enable.
- Select Resend Events and choose a time before the oldest Failed or Abandoned delivery on the endpoint's Deliveries tab, within the last 30 days. If none are left, go back the full 30 days.
wawa resends the failed and cancelled deliveries with their original contents, and sends the events raised while the
endpoint was off with each record as it is now. An event whose record has since been removed outright is skipped, as
there is nothing left to send. Watch them go out on the endpoint's Deliveries tab. Resending is safe to repeat:
every event keeps its Wawa-Event-Id, so a receiver that removes duplicates ignores what it already has.
To pause deliveries yourself, select Disable on the endpoint. That cancels the deliveries still waiting, so once you select Enable again, use Resend Events from before you paused, or from before the oldest delivery it cancelled if that is earlier. The Deliveries tab lists those as Abandoned.
Building a receiver that recovers
For the team that runs the receiver:
- Store first, answer 2xx, then process. If you reject an event because of what it contains, such as a missing field or a downstream system refusing it, wawa treats that as an outage: it retries the event for about a week, and it counts towards switching the endpoint off. Keep those events on your side for someone to fix instead.
- Remove duplicates by
Wawa-Event-Id. It is the same on every retry and resend. - Order by
sequence, not by arrival. Retries and resends arrive after later events. Keep the highestsequenceyou have seen for each record. Sequences are per account and per record type, so key this byWawa-Endpoint-Id, the record type and the record id. - Agree who acts on warnings. wawa's warnings go to the account's administrators. If someone else runs the receiver, agree with them who watches for the emails and who resends.
Verifying signatures, the headers and the event schemas are in the Webhooks Reference.
Report what happened after receipt
If your receiver processes webhooks asynchronously, it can report the final result to Connect.
Give its API client the webhook_outcomes:write scope and select it as the webhook endpoint’s
Outcome reporting client. Reporting starts with new deliveries. Removing or replacing the client revokes its access. An outstanding delivery then shows
Reporting disconnected and ages out after the usual retention period. Existing failure reports stay visible.
A replacement can report on its own deliveries. Restoring the original client lets it finish reporting on
its retained deliveries.
Use your OAuth bearer token to POST to /api/v2/webhook_deliveries/{delivery_id}/outcomes,
using the UUID from the original Wawa-Delivery-Id header. For example:
{
"sequence": 1,
"status": "failed",
"reason_code": "missing_required_field",
"provider_reference": "submission-42",
"sent": false
}
| Field | What to send |
|---|---|
sequence | A positive integer you increase for each new report about this delivery. This is local to your reports and independent of the webhook event sequence. |
status | accepted when processing succeeded, failed for a confirmed failure, skipped for an intentional omission, or unknown when the result is uncertain (for example, after losing an acknowledgement). |
reason_code | Required for failed, skipped and unknown results. Use a stable code of up to 80 letters, numbers, dots, underscores or hyphens. |
provider_reference | Optional opaque reference, up to 128 characters, for finding the submission in your system. |
sent | Required for a failed result. Send true if you sent the submission downstream and false if processing failed before that point. |
Report the result of the whole delivery. If processing fans out to multiple destinations, report acceptance once all required submissions succeed. Use the provider reference to find individual messages in your own system. Keep patient identifiers, clinical values and raw responses out of reports. An identical retry returns the same HTTP 204. Reusing a sequence with different details returns 409. A late report is retained in history. The highest sequence determines the displayed outcome.
Staff can open the originating event or delivery in Settings → Connect. On the endpoint’s Deliveries tab, Needs Attention includes failed and unknown outcomes, plus successful HTTP deliveries that have waited an hour for a report. Reporting an outcome records what happened. The provider remains responsible for downstream recovery.