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

# Incoming webhooks

> Receive data from external services and apps

Incoming webhooks let external apps send data into your Partnero account. Use them to automatically create partners, customers, or transactions when events occur in your other systems.

## How It Works

1. Create an incoming webhook in Partnero
2. Send sample data to the Test URL
3. Map the incoming fields to Partnero fields
4. Use the Production URL to send live data

## Creating an Incoming Webhook

<Steps>
  <Step title="Go to Incoming Webhooks">
    Navigate to **Program Settings → Incoming Webhooks** and click **Create an incoming webhook**.
  </Step>

  <Step title="Copy your URLs">
    You'll receive two URLs:

    * **Test URL** - Send sample data here first. No data is created in your account.
    * **Production URL** - Send real data here once mapping is configured.
  </Step>

  <Step title="Send test data">
    Send a sample JSON payload to your Test URL:

    ```bash theme={null}
    curl -X POST 'YOUR_TEST_URL' \
      -H 'Content-Type: application/json' \
      -d '{
        "user_email": "john@partnero.com",
        "user_name": "John Doe",
        "order_id": "12345",
        "total": 99.99
      }'
    ```
  </Step>

  <Step title="Select an action">
    Choose what you want to do with the incoming data:

    * **Create a partner** (Affiliate programs)
    * **Create a customer**
    * **Create a transaction**
  </Step>

  <Step title="Map the fields">
    Partnero parses your sample data and shows all available field paths. Map them to the required fields:

    | Your Data    | → | Partnero Field  |
    | ------------ | - | --------------- |
    | `user_email` | → | Email address   |
    | `user_name`  | → | Name            |
    | `order_id`   | → | Transaction key |
    | `total`      | → | Amount          |
  </Step>

  <Step title="Save and go live">
    Save your webhook configuration. Start sending real data to your Production URL.
  </Step>
</Steps>

## Available Actions

### Create a Partner

Available for **Affiliate programs**. Creates a new partner in your program.

| Field                 | Required | Description             |
| --------------------- | -------- | ----------------------- |
| Email address         | Yes      | Partner's email         |
| Name                  | Yes      | Partner's name          |
| Partner ID            | No       | Custom identifier       |
| Partner key           | No       | Custom referral key     |
| Referring partner key | No       | For multi-tier programs |

### Create a Customer

Creates a new customer linked to a partner.

| Field                | Required | Description               |
| -------------------- | -------- | ------------------------- |
| Email address        | Yes      | Customer's email          |
| Name                 | Yes      | Customer's name           |
| Customer key         | No       | Custom identifier         |
| Partner key/ID/email | No       | Links customer to partner |

**For Refer-a-Friend programs**, you can also specify:

* Referring customer key/email/ID

### Create a Transaction

Records a sale or purchase.

| Field           | Required | Description                      |
| --------------- | -------- | -------------------------------- |
| Amount          | Yes      | Transaction amount               |
| Customer key    | Yes      | Which customer made the purchase |
| Transaction key | No       | Unique identifier (recommended)  |
| Product ID      | No       | Product identifier               |
| Product type    | No       | e.g., `monthly`, `yearly`        |

## Example: Complete Flow

**1. Your external app sends order data:**

```json theme={null}
{
  "event": "order_completed",
  "customer": {
    "email": "buyer@partnero.com",
    "name": "Jane Smith"
  },
  "order": {
    "id": "ORD-789",
    "amount": 149.99,
    "product": "pro_plan"
  },
  "referral_code": "PARTNER123"
}
```

**2. Map the fields in Partnero:**

| Incoming Path    | Partnero Field  |
| ---------------- | --------------- |
| `customer.email` | Email address   |
| `customer.name`  | Name            |
| `order.id`       | Transaction key |
| `order.amount`   | Amount          |
| `order.product`  | Product ID      |
| `referral_code`  | Partner key     |

**3. Partnero automatically:**

* Finds or creates the customer
* Links them to the partner with key `PARTNER123`
* Creates the transaction
* Calculates commission

## Tips

<Tip>
  Always include a unique transaction key to prevent duplicates and enable refund tracking.
</Tip>

<Note>
  Field mapping is flexible—Partnero can extract values from nested JSON objects like `customer.email` or `order.details.total`.
</Note>

<Warning>
  Test URL requests don't create any data. Always verify your mapping works with test data before switching to the Production URL.
</Warning>