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

# POST /builtbybit — BuiltByBit License Key Webhook

> Public integration webhook endpoint called by BuiltByBit to request a license key when a customer downloads a resource.

This endpoint is called automatically by **BuiltByBit** when a buyer downloads a resource configured with an External License Key placeholder. Avalex verifies the shared secret, matches the product by BuiltByBit Resource ID, resolves or creates the customer profile, verifies that no double license is created, and responds with the license key in plain text.

```http theme={null}
POST https://api.avalex.com/builtbybit
```

Alternative paths supported: `POST /builtbybit/license` and `POST /integrations/builtbybit`.

<Note>
  This is an integration webhook endpoint. Authentication is handled via the `secret` parameter in the request payload rather than an HTTP Authorization header.
</Note>

<Warning>
  This endpoint is **rate limited to 60 requests per minute per IP address**. Exceeding this limit returns a `429 Too Many Requests` response.
</Warning>

***

## Request Parameters

BuiltByBit sends request data as form fields (`application/x-www-form-urlencoded` or `multipart/form-data`). JSON payloads (`application/json`) are also supported.

<ParamField body="secret" type="string" required>
  The secret key configured in both BuiltByBit placeholder settings and Avalex server configuration (`builtByBit.secret`).
</ParamField>

<ParamField body="user_id" type="string" required>
  The BuiltByBit User ID of the buyer downloading the resource.
</ParamField>

<ParamField body="resource_id" type="string" required>
  The BuiltByBit Resource ID of the product being downloaded. Must match a product's `builtByBitResourceId` in Avalex.
</ParamField>

<ParamField body="builtbybit" type="string">
  Flag sent by BuiltByBit (typically `"true"`).
</ParamField>

<ParamField body="steam_id" type="string">
  The Steam64 ID of the buyer (if linked on their BuiltByBit account). Stored in the customer's social profiles.
</ParamField>

<ParamField body="version_id" type="string">
  Internal version ID of the downloaded resource on BuiltByBit.
</ParamField>

<ParamField body="version_number" type="string">
  Release version string of the downloaded file (e.g. `1.2.0`). Recorded in the audit log.
</ParamField>

### Form Data Example

```bash theme={null}
curl -X POST https://api.avalex.com/builtbybit \
  -d "builtbybit=true" \
  -d "user_id=123456" \
  -d "resource_id=98765" \
  -d "steam_id=76561198000000000" \
  -d "version_number=1.0.0" \
  -d "secret=your-configured-secret"
```

***

## Response — 200 OK

Returns the raw license key as plain text with `Content-Type: text/plain; charset=UTF-8`:

```text theme={null}
XXXX-XXXX-XXXX-XXXX
```

<Note>
  BuiltByBit directly injects this plain text response at the location of the placeholder in the delivered file.
</Note>

***

## Processing Flow

| Step | Operation | Description |
| - | - | - |
| 1 | **Secret Check** | Compares `secret` with server config. If mismatched, returns `401 Unauthorized`. |
| 2 | **Product Lookup** | Finds product matching `builtByBitResourceId == resource_id`. If missing, returns `404 Not Found`. |
| 3 | **Customer Resolution** | Finds customer with `BuiltByBitID == user_id`. If none exists, creates a new customer profile. |
| 4 | **Active License Check** | Checks if the customer already owns a valid, non-expired license for this product. If so, returns that license key immediately. |
| 5 | **License & Order Creation** | Generates a new license key (inheriting product limits and subscription duration) and logs a new order. |
| 6 | **Audit Logging** | Records `builtbybit.license.create` or `builtbybit.license.reuse` in the audit log. |

***

## Error Responses

| Status | Body | Description |
| - | - | - |
| `400 Bad Request` | `Missing required form fields: user_id, resource_id, secret` | One or more required fields were missing from the payload. |
| `401 Unauthorized` | `Invalid secret` | The `secret` parameter does not match the configured server secret. |
| `404 Not Found` | `No product found with BuiltByBit resource ID <id>` | No product in Avalex has the specified `builtByBitResourceId`. |
| `429 Too Many Requests` | `Too many requests. Please try again shortly.` | The requesting IP has exceeded the 60 requests/min rate limit. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.