A pharmacy webhook can deliver order, refill, preparation, shipment, or correction events to adult family home software within seconds. That speed is useful only when the receiving system verifies who sent the message, rejects stale or altered payloads, processes repeats once, and reconciles every event with the intended pharmacy, facility, resident, and medication workflow.
This guide covers integration security and operations, not dispensing, clinical verification, or medication advice. It was reviewed on August 8, 2026. Facilities and pharmacies should define contractual, privacy, order-acceptance, incident-response, and continuity responsibilities for each integration.
Define an event contract
Publish a versioned schema for each event type:
- Pharmacy order submitted
- Order corrected or withdrawn
- Facility acceptance acknowledged
- Refill request received
- Refill status changed
- Shipment created or delivered
- Medication package exception
- Resident or facility mapping needs review
Require event ID, type, schema version, producer account, occurred time, created time, facility relationship reference, protected resource references, and payload.
Do not let the event type determine authorization by itself. Verify the producer and relationship before reading or applying resident fields.
Verify authenticity before parsing business data
Use HTTPS and a cryptographic message signature with a secret or public key dedicated to the integration. Verify against the exact raw request bytes before JSON normalization.
Check:
- Signature algorithm and key identifier
- Expected integration account
- Signed timestamp
- Exact raw-body digest
- Supported schema version
- Allowed endpoint and method
- Content length and type
The OWASP Web Service Security guidance explains transport protection and message-integrity controls. Publish the pharmacy integration's actual signing format and rotation process.
Reject unsigned, malformed, mismatched, or unknown-key events without exposing resident details.
Enforce a freshness window
Require a signed timestamp and reject messages outside a documented clock-skew and replay window. Compare server time, not a client browser clock.
Timestamp validation reduces reuse of captured messages but does not replace event deduplication. A legitimate provider may retry the same current event several times.
Monitor consistent clock differences and key-rotation mistakes. Do not widen the acceptance window indefinitely to hide integration drift.
Deduplicate by provider event ID
Reserve the provider account and event ID atomically before applying side effects. Store payload fingerprint, first-seen time, processing state, and final result.
When the identical event repeats, return the prior acknowledgement. When the same event ID carries a different payload fingerprint, quarantine it as an integrity conflict.
The API idempotency guide explains request keys, fingerprints, durable receipts, and business uniqueness.
Do not rely on a queue's at-most-once promise; retries can occur before and after the queue.
Validate the pharmacy-facility relationship
Resolve the authenticated pharmacy organization from its key, then verify that the referenced facility relationship is active and permits the event type.
A pharmacy serving many facilities must use a distinct relationship reference for each. Ending access to Facility Alpha cannot stop Facility Beta's valid traffic or let Alpha events arrive under Beta.
The server validates resident ownership inside the facility. A pharmacy-supplied resident ID is only a selector, never authorization.
Match residents conservatively
Prefer an established pharmacy-facility resident mapping created through an authorized matching workflow. Store pharmacy patient reference, facility resident ID, mapping status, verifier, and effective dates.
If the mapping is absent or conflicts, quarantine the event for review. Do not match automatically by name and date of birth, and never create a new resident from a medication event.
Show reviewers the minimum necessary identity evidence and block cross-facility candidates. Correcting the mapping should replay the quarantined business event idempotently.
Keep incoming orders pending
A verified webhook proves message origin and integrity; it does not activate a resident medication. Create an immutable incoming pharmacy submission containing the exact medication details and source timestamps.
The facility reviews resident, medication, strength, form, dose, route, schedule, dates, prescriber, warnings, dispensing detail, and optional notes. Exact administration instructions can remain optional when the workflow permits.
On acceptance, commit the order version and future schedule atomically. On rejection or correction request, preserve the original submission and send a linked response event.
Process state changes as a state machine
Define permitted transitions for order and refill events. For example, a refill may move from requested to acknowledged, preparing, ready or shipped, delivered, facility received, and closed.
Reject an impossible transition or route it for reconciliation. A late “preparing” event should not move a refill backward after verified receipt.
Use event occurred time and source sequence when available, but do not trust sequence alone when a payload conflicts with local evidence. Preserve the conflict and owner.
Separate transport acknowledgement from business acceptance
Return a quick authenticated response indicating received, duplicate, rejected signature, unsupported schema, or queued. Do not hold the webhook connection open for human facility acceptance.
Provide a durable processing status keyed by provider event ID. A transport-level 200 means the platform accepted responsibility for processing; it does not mean the facility accepted the medication.
Send business acknowledgement through a signed outbound webhook or protected API after the state transition completes.
Use an inbox and outbox
Store the verified inbound event before queueing its business processing. Use a transactional outbox for outbound acknowledgements and correction requests.
This prevents a crash from applying an order without recording the inbound evidence or committing acceptance without notifying the pharmacy.
Each outbox item has a stable ID, destination relationship, payload version, retry state, and final provider receipt. Retry transient delivery failures without recreating the underlying business event.
Rotate keys safely
Support overlapping current and next keys during a bounded rotation window. Identify keys without exposing secret material and audit creation, activation, use, revocation, and deletion.
Reject signatures from revoked keys immediately. Do not put shared secrets in URLs, browser storage, support tickets, or general logs.
Test rollback if the pharmacy activates the wrong key. Emergency rotation should preserve queued events for later verified replay rather than accepting unsigned traffic.
Protect payloads and diagnostics
Medication webhooks contain sensitive resident data. Encrypt transport and protected storage, restrict queue and event views, and minimize retention of redundant raw payloads under the approved policy.
Log provider event ID, opaque facility and resident references, signature result, schema version, error code, and processing status. Exclude full names, medication directions, tokens, signatures, and raw bodies from general telemetry.
Support access to payloads must be case-bound, time-limited, and audited.
Reconcile expected and actual state
Run independent checks for:
- Verified events stuck before business processing
- Incoming orders without pending or terminal status
- Accepted orders without resident medication and schedule
- Refill events that moved backward
- Delivered items without facility receipt after the expected window
- Outbound acknowledgements exhausted after retry
- Mapping corrections with quarantined events still open
- Duplicate IDs with conflicting fingerprints
Reconciliation should query authoritative business records, not merely the webhook queue.
Provide an integration operations console
Use tabs for inbound events, quarantined mappings, processing exceptions, outbound acknowledgements, key status, and reconciliation.
Show event ID, pharmacy, facility, type, occurred and received times, signature result, current business status, attempt count, and owner. Hide raw resident content until an authorized operator deliberately opens it.
Offer bounded replay only after previewing the event, target relationship, existing result, and expected side effect.
Export a sanitized reconciliation manifest for joint pharmacy-facility review. It should list event IDs, types, timestamps, facility relationship, processing outcomes, and open owners without copying medication directions or resident names into an ordinary support file.
Test attacks and delivery failures
Use synthetic facilities and residents to verify:
- Valid signed event processes once.
- Body changes after signing.
- Unknown and revoked keys.
- Timestamp outside the freshness window.
- Identical event delivered repeatedly.
- Same ID with a changed fingerprint.
- Event references an unapproved facility.
- Resident mapping belongs to another facility.
- Order remains pending until acceptance.
- Duplicate acceptance creates one schedule.
- Refill events arrive out of order.
- Business worker stops after inbox commit.
- Outbound acknowledgement retries.
- Key rotation overlap and emergency revocation.
- Quarantined mapping is corrected and replayed once.
- Reconciliation finds an accepted order without schedule.
Inspect integration ledgers, resident orders, refill state, schedules, alerts, and audit history.
Frequently asked questions
Does HTTPS remove the need for a webhook signature?
No. TLS protects transport; a verified message signature and account relationship establish expected origin and payload integrity at the endpoint.
Should repeated events return an error?
Return the prior result for an identical known event. Repeated delivery is normal; changed payload under the same ID is a conflict.
Can a signed pharmacy order activate medication automatically?
Not when facility acceptance is required. Store it as verified incoming evidence and activate only after authorized review.
What if events arrive out of order?
Apply a defined state machine, preserve source time and sequence, and reconcile conflicts instead of blindly accepting the last arrival.
Can support see raw webhook payloads?
Only through protected, case-bound, time-limited access when necessary. General logs should contain opaque references and error codes.
Make real-time pharmacy integration verifiable
Secure webhooks combine raw-body signatures, freshness checks, event deduplication, facility-resident authorization, pending order review, state machines, durable inbox/outbox records, and independent reconciliation.
Explore AFH Manager to test signed pharmacy events, mapping quarantine, medication acceptance, refill sequencing, key rotation, replay handling, and reconciliation with synthetic integrations.