Skip to main content

Fulfillment Authorization Requested

The FULFILLMENT_AUTHORIZATION_REQUESTED event is triggered when an approved case decision needs your organization's authorization before the order can be placed automatically, and no active authorization period covers that fill.

If an active authorization period already covers the fill, the order is placed automatically and no webhook is sent.

Availability​

  • This event is sent only to organizations that handle their own patient payments. Organizations that don't handle their own payments never receive it, even if they subscribed.
  • Your organization must have an enabled webhook subscription to this event. Turning on payment ownership is rejected without one.
  • Access is limited to organizations CareValidate has enabled for this flow.

Responding​

Answer by calling POST /api/v1/fulfillment-authorization with the requestId from this payload.

  • Replying with validFor authorizes that many months of treatment, so later fills in that time won't trigger new requests.
  • Replying without validFor authorizes only this fill.

See the endpoint page for the full request format and responses.

A request can become unnecessary if the CareValidate support team places the order manually first. A reply sent after that returns a 400 error with code CASE_ERROR. Nothing is applied, so don't treat this error as a failure to retry.

Known limitations

This event does not fire for every approved decision. If an active authorization period already covers the fill, the order is placed without a webhook, so don't assume every approved decision triggers this event.

Unlike most other case webhooks, this payload does not include a case object. The activity object may be null, so don't rely on it.

Attributes​

eventstring
The name of the event that was triggered. For this webhook, the value will always be `FULFILLMENT_AUTHORIZATION_REQUESTED`.
payloadobject
The main object containing all data related to the event. Unlike most other case webhooks, this payload does not include a `case` object.
Show child attributes
caseIdstring<UUID>
The unique identifier of the case this decision belongs to.
requestIdstring<UUID>
A unique identifier for this specific authorization request. Send this value back exactly as received when replying via `POST /api/v1/fulfillment-authorization`.
decisionIdstring<UUID>
The unique identifier of the approved decision this request is for.
organizationProductIdstring<UUID>
Optional. The identifier of your organization's product for the treatment. Included only when known; absent otherwise.
reasonstring
Always present. Always the fixed text `No active fulfillment authorization covers this fill`.
latestFulfillmentAuthorizationobject
Optional. Describes the treatment's most recent authorization period. Absent if the treatment has never had an authorization period. A period that has run out or ended explains why this request was sent, and you can use these values to decide how many months to authorize next.
Show child attributes
validForobject
The validity that was granted for that period.
Show child attributes
intervalstring
Allowed values:day,week,month,year
The unit of the period.
intervalCountnumber
The number of intervals granted.
consumednumber
A whole number, in the same unit as `validFor.interval`, of how much of the period has been used. Counts shipped fills only and never exceeds `validFor.intervalCount`.
activatedAtstring<date-time> | null
When the period started, or `null` if it has not started.
closedAtstring<date-time> | null
When the period ended, or `null` if it has not ended.
activityobject
The standard case activity object. May be `null`; don't assume it is always populated.
Show child attributes
idstring<UUID>
The unique identifier for this activity log entry.
typestring
Allowed values:CREATE_CASE,CHANGE_CASE_STATUS,ADD_CASE_COMMENT,DELETE_CASE_COMMENT,ADD_CASE_DECISION,ARCHIVE_CASE,ESCALATE_CASE,DEESCALATE_CASE,ADD_CASE_ESCALATION,REMOVE_CASE_ESCALATION,UPDATE_CASE_ESCALATION,DECISION_DELETED,ADD_CASE_ATTACHMENT,ADD_CASE_ASSIGNEE,REMOVE_CASE_ASSIGNEE,IMPORT_CASE,ADD_FORM_RESPONSE,UPDATE_FORM_RESPONSE,ADD_HR_REP,REMOVE_HR_REP,DELETE_ATTACHMENT,FOLLOWUP_EMAIL,PAYMENT_ADDED,PAYMENT_COMPLETED,PAYMENT_DELETED,PAYMENT_UPDATED,ORDER_CREATED,TEXT_INFO,REOPEN_CASE,SMS_SENT,SMS_RECEIVED,INBOUND_EMAIL,OUTBOUND_EMAIL,FOLLOWUP_FORM,ORDER_STATUS_CHANGED,ORDER_TRACKING_ADDED,PAYMENT_INFO_LINK_SENT,ADD_PAYMENT_INFO_USING_LINK,CALENDAR_EVENT_CREATED,CALENDAR_EVENT_RESCHEDULED,CALENDAR_EVENT_CANCELED,CALENDAR_EVENT_NO_SHOW,CALENDAR_EVENT_NO_SHOW_REMOVED,SUPPORT_NOTE_ADDED,SUPPORT_NOTE_UPDATED,SUPPORT_NOTE_COMPLETED,COMMENT_ACKNOWLEDGED,NOTE_ACKNOWLEDGED,VISIT_TYPE_CHANGED,PAYMENT_PREAUTHORIZED,SUBSCRIPTION_ADDED,SUBSCRIPTION_ACTIVATED,SUBSCRIPTION_COMPLETED,SUBSCRIPTION_PAUSED,SUBSCRIPTION_RESUMED,SUBSCRIPTION_CANCELLED,SUBSCRIPTION_UPDATED,ADD_CASE_PRODUCT,CLOSE_CASE_PRODUCT,OPEN_CASE_PRODUCT,FULFILLMENT_AUTHORIZATION_REQUESTED
The type of activity.
isPHIboolean
Indicates if the activity contains Protected Health Information (PHI).
isRestrictedboolean
Indicates if the activity details are restricted to internal users due to sensitivity (for example, payment data).
valueBeforestring | null
The previous value before this activity, if any. For this event, usually `null`.
valueAfterstring | null
A short description of the result of the activity, such as `payment info has been added`.
timestampstring<date-time>
The exact timestamp when the activity occurred.
actorobject
The user who performed the action (i.e., who added the new assignee).
Show child attributes
idstring<UUID>
The ID of the actor.
firstNamestring
The first name of the actor.
lastNamestring
The last name of the actor.
emailstring
The email of the actor.
targetUserobject
The user who was the target of the action (i.e., the user who was assigned).
Show child attributes
idstring<UUID>
The ID of the assigned user.
firstNamestring
The first name of the assigned user.
lastNamestring
The last name of the assigned user.
emailstring
The email of the assigned user.

Response​

{
  "event": "FULFILLMENT_AUTHORIZATION_REQUESTED",
  "payload": {
    "caseId": "ec7ebb4c-3a36-43bf-93f7-3c292020c281",
    "requestId": "b1e6a1a2-9b3e-4b8a-9b7a-1f2c3d4e5f60",
    "decisionId": "3c9d6f0e-7a41-4f55-8f0a-2b6d1e9c4a77",
    "organizationProductId": "d2f1a8b4-6c3e-4a9b-8e57-0f4c9a1b7e23",
    "reason": "No active fulfillment authorization covers this fill",
    "latestFulfillmentAuthorization": {
      "validFor": {
        "interval": "month",
        "intervalCount": 3
      },
      "consumed": 3,
      "activatedAt": "2025-06-10T17:02:11.000Z",
      "closedAt": "2025-09-03T23:24:30.000Z"
    },
    "activity": {
      "id": "58a5e76c-f737-4c29-8077-837a545791f0",
      "type": "FULFILLMENT_AUTHORIZATION_REQUESTED",
      "isPHI": false,
      "isRestricted": false,
      "timestamp": "2025-09-03T23:24:31.127Z",
      "valueBefore": null,
      "valueAfter": null,
      "actor": {
        "id": "35153fb8-b917-469a-ac8b-3e692da9c287",
        "firstName": "Auto",
        "lastName": "Notifier",
        "email": "auto-notifier@carevalidate.com"
      },
      "targetUser": null
    }
  }
}