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

# Webhooks

> Receive card delivery data via webhook when your program uses webhook-based communication.

When a program is configured to deliver cards via webhook, iQpay sends a `POST` request to your configured endpoint with the card activation details and member information.

<Note>
  Webhook endpoints are configured during program setup in the iQpay Admin portal.
</Note>

## Webhook Payload

When an order is created and the program uses webhook delivery, iQpay sends the following payload to your endpoint:

<ResponseField name="activation_code" type="object">
  Card activation details.

  <Expandable title="Activation code fields">
    <ResponseField name="url" type="string">
      The card activation URL to deliver to the member.
    </ResponseField>

    <ResponseField name="code" type="string">
      iQpay generated verification code.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of the card (empty string).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="member" type="object">
  Member details associated with the order.

  <Expandable title="Member fields">
    <ResponseField name="first_name" type="string">
      Member's first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Member's last name.
    </ResponseField>

    <ResponseField name="email" type="string">
      Member's email address.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Member's mobile number.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      Sponsor's external identifier for the member.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="external_transaction_id" type="string">
  The sponsor-supplied identifier for tracing, matching the value sent in the Create Order request.
</ResponseField>

## Example Payload

```json theme={null}
{
  "activation_code": {
    "url": "https://activate.iqpay.com/card/abc123",
    "code": "ACT-789XYZ",
    "status": ""
  },
  "member": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "member@example.com",
    "phone_number": "5551234567",
    "external_id": "EXT-MBR-12345"
  },
  "external_transaction_id": "TXN-2024-00001"
}
```

## Scheduled Orders

When an order includes a `processingDate` set in the future, the webhook is **not** sent at the time the order is placed. Instead, iQpay holds the order until the scheduled processing date arrives, then processes the order and sends the webhook payload at that time.

The API returns a `200` or `201` response immediately to confirm the order was accepted, but card activation details are only delivered via webhook once the order is actually processed on the scheduled date.

| Scenario                              | Webhook Timing                                                 |
| ------------------------------------- | -------------------------------------------------------------- |
| No `processingDate` (or `null`)       | Webhook sent immediately after order creation                  |
| `processingDate` set to a future date | Webhook sent on the scheduled date when the order is processed |

## Response

Your webhook endpoint **must** return a `200` HTTP status code on success. Any other status code is treated as a failure.

<Warning>
  If your webhook fails to respond with `200`, the card delivery notification may not be retried automatically. Ensure your endpoint is reliable and handles errors gracefully.
</Warning>

## Testing

In the Demo environment, configure a test webhook endpoint (e.g., using a service like [webhook.site](https://webhook.site)) to inspect payloads during integration.