Recipient RFI Webhooks

Use recipient RFI webhooks to find out when we need information about a recipient and when the case moves to a new review stage. The four events mirror the transaction RFI events and carry the same payload shape; only the event name and the subject differ.

Treat every webhook as a notification that something changed, not as the complete case. After you receive an event, retrieve the case before deciding what to do next.

Handle every recipient RFI webhook

Verify the webhook signature.
Deduplicate the delivery using the X-Webhook-Event-Id request header.
Read the case_id from resource.id.
Retrieve the latest case from GET /v1/customers/{customer_id}/rfi-cases/{case_id}.
If the case shows ACTION_REQUIRED, respond to every requirement marked ACTION_REQUIRED.
Keep a slower polling job running with subject_type=RECIPIENT&updated_from=... so you can recover any event you missed.

Events you can receive

Event	What happened	What you should do
`rfi.recipient.action_required`	We need a new or corrected response from you. You may receive this event more than once for the same case.	Retrieve the case and send the requested TEXT or FILE information.
`rfi.recipient.answered`	We received everything requested in the current round and can continue our review.	No response is needed right now. Keep monitoring the case.
`rfi.recipient.rejected`	We rejected the RFI case.	Stop sending new information to the case and retrieve the recipient separately for its `status`.
`rfi.recipient.closed`	We completed our review and closed the case.	No action is needed unless we reopen the case and request more information.

A returned FILE or TEXT response is not the same as a rejected case. When a response needs correction, its requirement returns to ACTION_REQUIRED, and we send another rfi.recipient.action_required event. Read data.note for the latest instructions.

None of these events changes the recipient. Approval or rejection of the recipient itself arrives as recipient.approved or recipient.rejected; see Recipient webhooks.

Delivery and reconciliation

Webhook delivery is asynchronous and at least once. An event may arrive late or more than once, and events may not arrive in the same order as the case changes. Always retrieve the case for its current status, and use the list endpoint with subject_type=RECIPIENT and updated_from as a recovery check. See Webhooks for signature verification, retries, and delivery headers.

Find the case and the recipient

Every recipient RFI event identifies the case that changed and the recipient it is about:

{
  "event_name": "rfi.recipient.answered",
  "resource": {
    "type": "rfi_cases",
    "id": "TC-3N7Q-D2KV"
  },
  "data": {
    "case_id": "TC-3N7Q-D2KV",
    "subject": {
      "type": "RECIPIENT",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Field	How to use it
`event_name`	Use this to route the event to the right handler.
`resource.type`	This is always `rfi_cases` for RFI events.
`resource.id`	This is the RFI `case_id`. Use it to retrieve the case.
`data.case_id`	This repeats the same `case_id` for convenience.
`data.subject.type`	Always `RECIPIENT` for these events.
`data.subject.id`	The `recipient_id`. Use it to retrieve the recipient. There is no `transaction_type` on a recipient subject.

The event body does not contain the delivery ID. Use the X-Webhook-Event-Id request header when you deduplicate deliveries.

When we need more information

We send rfi.recipient.action_required when a FILE or TEXT requirement needs a response. The event includes a stable data.requirement_id so you can correlate it with the case, but you do not send that ID back when responding.

FILE requirement

{
  "event_name": "rfi.recipient.action_required",
  "resource": {
    "type": "rfi_cases",
    "id": "TC-3N7Q-D2KV"
  },
  "data": {
    "case_id": "TC-3N7Q-D2KV",
    "subject": {
      "type": "RECIPIENT",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "action": "SUBMIT_INFORMATION",
    "requirement_id": "RQ-9F4C-T2LN",
    "requirement_type": "FILE",
    "accepted_document_types": ["STANDARD_RECIPIENT_INFORMATION"],
    "note": "Please provide the signed agreement with this recipient."
  }
}

Retrieve the case, then send a multipart FILE response whose document_type is one of the accepted_document_types. Do not include requirement_id in the submission path or body.

TEXT requirement

{
  "event_name": "rfi.recipient.action_required",
  "resource": {
    "type": "rfi_cases",
    "id": "TC-3N7Q-D2KV"
  },
  "data": {
    "case_id": "TC-3N7Q-D2KV",
    "subject": {
      "type": "RECIPIENT",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "action": "SUBMIT_INFORMATION",
    "requirement_id": "RQ-5K2P-M8WD",
    "requirement_type": "TEXT",
    "note": "Please describe your business relationship with this recipient."
  }
}

The webhook note tells you what we need. Retrieve the case, then send your answer in the JSON text field:

{
  "type": "TEXT",
  "text": "Acme Software Inc is our payroll software vendor under a two-year contract."
}

When we have the current response

We send rfi.recipient.answered after we receive everything requested in the current round. The case is now ANSWERED and waiting for our review, and the recipient's action_required is null again.

You do not need to respond to this event. Keep monitoring the case because we may ask for more information later. If that happens, the case returns to ACTION_REQUIRED, and we send a new rfi.recipient.action_required event.

When we reject the case

We send rfi.recipient.rejected when we reject the RFI case. The event does not include an internal rejection reason.

The RFI case and the recipient have separate outcomes. A rejected case does not reject the recipient; retrieve the recipient separately for its status, or wait for recipient.approved or recipient.rejected.

{
  "event_name": "rfi.recipient.rejected",
  "resource": {
    "type": "rfi_cases",
    "id": "TC-3N7Q-D2KV"
  },
  "data": {
    "case_id": "TC-3N7Q-D2KV",
    "subject": {
      "type": "RECIPIENT",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

When we close the case

We send rfi.recipient.closed when our review is complete and the case moves to CLOSED. Closing the case does not change the recipient's status; the recipient may already have been approved before the case closes.

{
  "event_name": "rfi.recipient.closed",
  "resource": {
    "type": "rfi_cases",
    "id": "TC-3N7Q-D2KV"
  },
  "data": {
    "case_id": "TC-3N7Q-D2KV",
    "subject": {
      "type": "RECIPIENT",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

If we reopen the case and need another response, you will receive rfi.recipient.action_required.

Related guides

Recipient RFI Overview explains the end-to-end flow and the recipient's action_required field.
RFI Webhooks covers the rfi.transaction.* events.
Webhook overview explains signature verification, retries, and delivery headers.