Skip to main content

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 failureWhat happens
Straight awaywawa 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 soOn 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 weekOnce 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 daysResend 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​

  1. Fix the receiver.
  2. In Settings → Connect → Webhooks, open the endpoint and select Enable.
  3. 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 highest sequence you have seen for each record. Sequences are per account and per record type, so key this by Wawa-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
}
FieldWhat to send
sequenceA positive integer you increase for each new report about this delivery. This is local to your reports and independent of the webhook event sequence.
statusaccepted 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_codeRequired for failed, skipped and unknown results. Use a stable code of up to 80 letters, numbers, dots, underscores or hyphens.
provider_referenceOptional opaque reference, up to 128 characters, for finding the submission in your system.
sentRequired 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.