> ## Documentation Index
> Fetch the complete documentation index at: https://developer.accessrc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# New Delivery Request Sent

## Overview

This document describes the **New Delivery Request** webhook event, where the **Service Provider** subscribes to the `DELIVERY_REQUEST_SENT` event in AccessRC. When the **Program Manager** creates a delivery request for a specific application group related to an assistance program that the **Service Provider** is configured for, AccessRC sends a webhook call to the callback service of the Service Provider with the delivery request details for integration.

***

## Event Flow: AccessRC → Service Provider

1. **Service Provider** subscribes to the `DELIVERY_REQUEST_SENT` event.
2. When a delivery request is created, AccessRC sends a webhook call to the service provider's callback URL.
3. The Service Provider processes the details of the delivery request and integrates it into their system.

***

<p align="center">
  <img src="https://mintcdn.com/canpeker/ezlmTUGMKwmp_MYx/images/newDeliveryRequest.svg?fit=max&auto=format&n=ezlmTUGMKwmp_MYx&q=85&s=bae41e040fb10d247a1067e30a18365d" width="798" height="965" data-path="images/newDeliveryRequest.svg" />
</p>

| Field                     | Description                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| deliveryRequestId         | Unique identifier (UUID) of the delivery request within AccessRC. Used to track, reference, and manage the specific delivery operation.                                                |
| providerDeliveryChannelId | Unique identifier (UUID) of the delivery channel through which this request will be executed (e.g., MoneyGram, IBAN Transfer). Links the delivery to a defined provider configuration. |
| assistanceProgramId       | Unique identifier (UUID) of the Assistance Program within AccessRC                                                                                                                     |
| description               | A human-readable description of the delivery request, typically summarizing its purpose, campaign, or activity (e.g., “Ukraine Winterization Cash Delivery”).                          |
| delivery                  | Array containing one or more delivery records for individual beneficiaries under this request. Each item represents a single transaction.                                              |
| deliveryId                | Unique identifier (UUID) of the individual delivery record within AccessRC. Used for internal tracking and reconciliation.                                                             |
| beneficiaryId             | Unique identifier of the beneficiary receiving this delivery. Used to map the transaction to a registered recipient in AccessRC.                                                       |
| deliveryOptions           | List of key–value pairs containing delivery-specific input data required by the provider (e.g., bank details, account identifiers).                                                    |
| key                       | The field name expected by the provider (e.g., iban, bankName, swiftCode).                                                                                                             |
| value                     | The corresponding field value provided for that key.                                                                                                                                   |
| amount                    | The total amount or quantity assigned to this delivery (e.g., 120).                                                                                                                    |
| unit                      | The unit of the delivery amount (e.g., EUR, USD, PCS).                                                                                                                                 |

## Webhook Request Payload

### CASH - Delivery

```json theme={null}
{
    "deliveryRequestId": "2372dd86-1e5d-4110-97ba-ff3c4237a74f",
    "providerDeliveryChannelId": "36cd4d29-e332-47b9-9ceb-f084fe5b0446",
    "assistanceProgramId": "553dad44-a2c2-493a-ab74-564fbcb59719",
    "description": "Ukraine Winterization Cash Delivery",
    "delivery": [
        {
            "deliveryId": "6fd1ca79-1a5d-4bd9-a4c9-b41c48ff6b7a",
            "beneficiaryId": "WU-949966281_1de2b7a4",
            "deliveryOptions": [
                {
                    "key": "iban",
                    "value": "UA629492312998229455975734891"
                },
                {
                    "key": "bankName",
                    "value": "PrivatBank"
                },
                {
                    "key": "swiftCode",
                    "value": "PBANUA2XXXX"
                }
            ],
            "amount": "120",
            "unit": "EUR"
        }
    ]
}
```

### VOUCHER - Delivery

```json theme={null}
{
    "deliveryRequestId": "2372dd86-1e5d-4110-97ba-ff3c4237a74f",
    "providerDeliveryChannelId": "36cd4d29-e332-47b9-9ceb-f084fe5b0446",
    "assistanceProgramId": "553dad44-a2c2-493a-ab74-564fbcb59719",
    "description": "1st Month Hygiene Kits",
    "delivery": [
        {
            "deliveryId": "6fd1ca79-1a5d-4bd9-a4c9-b41c48ff6b7a",
            "beneficiaryId": "WU-949966281_1de2b7a4",
            "deliveryOptions": [
                {
                    "key": "fullName",
                    "value": "John Doe"
                },
                {
                    "key": "email",
                    "value": "johndoe@gmail.com"
                }
            ],
            "amount": "2",
            "unit": "pcs"
        }
    ]
}
```

## Webhook Response Payload

### 200 Response Success

A successful callback response from the Service Provider’s callback service.

```json theme={null}
{
    "status": "success",
    "message": "Callback successfully received",
    "data": {}
}
```

### 400 Response

If the validation fails or there is a bad request, the response will be:

```json theme={null}
{
    "status": "failed",
    "error": {
        "code": 400,
        "message": "Validation failed. Please check your input.",
        "type": "BadRequest"
    }
}
```

### 401 Response

If the verification fails, the response will be:

```json theme={null}
{
    "status": "failed",
    "error": {
        "code": 401,
        "message": "Verification failed",
        "type": "Unauthorized"
    }
}
```

### 500 Response

In case of an internal server error, the response will be:

```json theme={null}
{
    "status": "failed",
    "error": {
        "code": 500,
        "message": "Internal Server Error",
        "type": "Exception"
    }
}
```