Test statuses and webhook events

Prior-authorization status changes are delivered to the HTTPS endpoint configured for your organization. Test requests use the same audit, outbox, signing, delivery, and retry path as live requests.

Test the receiver without patient data

Queue a signed prior_authorization.webhook_test event with an empty data object:

curl --request POST \
  --url https://api-staging.taigabilling.com/api/prior-authorizations/v1/webhook-endpoint/test \
  --header "Authorization: Bearer $TAIGA_API_KEY"

The response includes the event ID and a PENDING delivery status. GET /api/prior-authorizations/v1/webhook-endpoint reports the latest event’s attempt count, last HTTP status or error code, delivery state, and the total number of abandoned events.

After correcting a receiver, replay one abandoned event explicitly:

curl --request POST \
  --url https://api-staging.taigabilling.com/api/prior-authorizations/v1/webhook-endpoint/replay \
  --header "Authorization: Bearer $TAIGA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"event_id":"0d81ce44-5c51-4ad3-a1d9-3bdb13cb98ad"}'

Only events in ABANDONED state can be replayed. A replay resets the retry counter and sends the same event ID and payload again, so receivers should continue deduplicating successfully processed events by webhook-id.

Trigger a test outcome

Create a prior authorization with test_mode: true. Test requests require valid, in-scope patient, coverage, provider, and facility IDs, but they are never submitted to a payer or added to Taiga’s review queue.

Create request field

{
  "test_mode": true
}

The create request first produces a prior_authorization.received event. Use the returned request id to trigger one of the supported test outcomes:

curl --request POST \
  --url https://api-staging.taigabilling.com/api/prior-authorizations/v1/pa_test_123/test-status \
  --header "Authorization: Bearer $TAIGA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"status":"NEEDS_INFORMATION"}'

status must be NEEDS_INFORMATION, PARTIALLY_APPROVED, or DENIED. A terminal test outcome cannot be changed; create a separate test request for each terminal scenario. The endpoint is available in staging and production, but it rejects every request that was not explicitly created with test_mode: true.

Delivery headers

Every delivery includes:

content-type: application/json
user-agent: Taiga-Webhooks/1.0
webhook-id: 0d81ce44-5c51-4ad3-a1d9-3bdb13cb98ad
webhook-timestamp: 1785733200
webhook-signature: v1,BASE64_HMAC_SHA256_SIGNATURE

Use webhook-id as the delivery idempotency key. Verify webhook-signature against the exact raw request body before parsing JSON. The signed content is:

{webhook-id}.{webhook-timestamp}.{raw-body}

The signature is HMAC-SHA256 encoded as standard Base64. The signing secret is returned when you configure or read your webhook endpoint.

`NEEDS_INFORMATION`

{
  "id": "0d81ce44-5c51-4ad3-a1d9-3bdb13cb98ad",
  "type": "prior_authorization.needs_information",
  "created_at": "2026-08-03T04:20:00.000Z",
  "data": {
    "prior_authorization": {
      "approved_unit_type": null,
      "approved_units": null,
      "authorized_service_lines": [],
      "billing_provider_npi": "1234567890",
      "determined_at": null,
      "effective_date": null,
      "expiration_date": null,
      "external_id": "integration-test-needs-information",
      "id": "pa_test_needs_information",
      "last_status_at": "2026-08-03T04:20:00.000Z",
      "portal_reference_number": null,
      "prior_authorization_number": null,
      "requirements_checked_at": "2026-08-03T04:20:00.000Z",
      "status": "NEEDS_INFORMATION",
      "status_message": "Test outcome: additional clinical information is required to continue review.",
      "submission_channel": null,
      "submission_destination": null,
      "submitted_at": null,
      "test_mode": true
    }
  }
}

`PARTIALLY_APPROVED`

The test result approves half of the requested units on the first service line, rounded down with a minimum of one.

{
  "id": "8752abf3-58ce-4ec7-a8ac-f82ad85210a7",
  "type": "prior_authorization.partially_approved",
  "created_at": "2026-08-03T04:25:00.000Z",
  "data": {
    "prior_authorization": {
      "approved_unit_type": "UNITS",
      "approved_units": 12,
      "authorized_service_lines": [
        {
          "approved_units": 12,
          "effective_date": "2026-08-04",
          "expiration_date": "2026-09-15",
          "modifiers": [],
          "procedure_code": "97110",
          "unit_type": "UNITS"
        }
      ],
      "billing_provider_npi": "1234567890",
      "determined_at": "2026-08-03T04:25:00.000Z",
      "effective_date": "2026-08-04",
      "expiration_date": "2026-09-15",
      "external_id": "integration-test-partial-approval",
      "id": "pa_test_partial_approval",
      "last_status_at": "2026-08-03T04:25:00.000Z",
      "portal_reference_number": "TEST-PORTAL-TIALAPPROVAL",
      "prior_authorization_number": "TEST-AUTH-TIALAPPROVAL",
      "requirements_checked_at": "2026-08-03T04:25:00.000Z",
      "status": "PARTIALLY_APPROVED",
      "status_message": "Test outcome: 12 units approved.",
      "submission_channel": "API",
      "submission_destination": "Taiga test payer",
      "submitted_at": "2026-08-03T04:25:00.000Z",
      "test_mode": true
    }
  }
}

`DENIED`

{
  "id": "3c447faf-450d-46b1-87ed-aad1bf891291",
  "type": "prior_authorization.denied",
  "created_at": "2026-08-03T04:30:00.000Z",
  "data": {
    "prior_authorization": {
      "approved_unit_type": null,
      "approved_units": null,
      "authorized_service_lines": [],
      "billing_provider_npi": "1234567890",
      "determined_at": "2026-08-03T04:30:00.000Z",
      "effective_date": null,
      "expiration_date": null,
      "external_id": "integration-test-denied",
      "id": "pa_test_denied",
      "last_status_at": "2026-08-03T04:30:00.000Z",
      "portal_reference_number": "TEST-PORTAL-PATESTDENIED",
      "prior_authorization_number": null,
      "requirements_checked_at": "2026-08-03T04:30:00.000Z",
      "status": "DENIED",
      "status_message": "Test outcome: the requested services did not meet plan requirements.",
      "submission_channel": "API",
      "submission_destination": "Taiga test payer",
      "submitted_at": "2026-08-03T04:30:00.000Z",
      "test_mode": true
    }
  }
}

Return any 2xx response after accepting an event. Failed deliveries are retried with exponential backoff and may be delivered more than once, so consumers must deduplicate by webhook-id.