# receiveWebhookCallback

Webhook Callback Endpoint

`POST /webhook/callback`

**API:** Avalara Item Classification API
**Tag:** WebhookCallback
**API Version:** 16.0.1-oas3
**Base URL:** https://api-sandbox.classification.avalara.net
**Authentication:** Basic (username + license key) or Bearer token

Source: https://developer.avalara.com/products/item-classification/api/methods/WebhookCallback/receiveWebhookCallback/

## Description

This is the endpoint that clients need to implement to receive webhook callbacks when classifications are completed.
Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint.

**Authentication:**
The webhook callback supports two authentication methods:
- Basic Authentication: Avalara will send an Authorization header with "Basic {token}"
- OAuth: Avalara will send an Authorization header with "Bearer {token}"

**Response Requirements:**
- The endpoint should return HTTP 200 or 201 on success
- The recommended response format is: {"name":"API_RESPONSE","value":"SUCCESSFUL"}
- For errors, return HTTP 400 with: {"name":"API_RESPONSE","value":"ERROR"}

**Retry Behavior:**
If the webhook call fails due to server connectivity issues, the system will automatically retry the call.
Clients should ensure their webhook endpoint is reliable and responds quickly to avoid retry delays.

## Request Body

**Content-Type:** `application/json; charset=utf-8`
**Schema:** `WebhookCallbackRequest`

The webhook callback payload that will be sent to the client's webhook endpoint when a classification is completed.
Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint.
This is an optional feature for "Item Classification Without Storage" customers.

**Authentication:**
The webhook callback supports two authentication methods:
- Basic Authentication: Requires an API key configured in the Avalara system
- OAuth: Requires an OAuth token endpoint to be configured in the Avalara system

**Conditional Fields:**
- The `hsCode` field is included for HS classification activities such as `hs6`, `hsFull`, and export HS flows
- The `eccnCode` and `countryOfExport` fields are included for ECCN classification activities when available
- The `countryOfOrigin` field is included for COO classification activities when available
- The `possibleHsCodes` field is only included when the `broker` parameter is set to "true" and there are alternative HS codes available

**Retry Behavior:**
If the webhook call fails due to server connectivity issues, the system will automatically retry the call.

| Property | Type | Required | Description |
|---|---|---|---|
| `hsClassificationId` | string | **Yes** | The id of the HS classification request that was completed. Example: `1234-SKU001-CA`. |
| `companyId` | string | **Yes** | The ID of the company that owns this item. Example: `3402`. |
| `itemCode` | string | **Yes** | The unique item code (typically your SKU) that was classified. Example: `ABC123`. |
| `countryOfDestination` | string | **Yes** | The country code for which the classification was performed. Example: `CA`. |
| `countryOfExport` | string | No | The export country code for ECCN classification results, when available. Example: `US`. |
| `countryOfOrigin` | string | No | The country of origin for COO classification results, when available. Example: `CN`. |
| `status` | string | **Yes** | The status of the classification request. Values: `CLASSIFIED`, `CANNOT_BE_CLASSIFIED`. Example: `CLASSIFIED`. |
| `hsCode` | string | No | The HS classification result for HS classification activities. Example: `320250`. |
| `eccnCode` | string | No | The export-control classification result for ECCN classification activities. Example: `5A001.a`. |
| `rationale` | string | No | Explanation of the classification decision when available. Example: `This item is classified as a night gown based on its material composition and intended use.`. |
| `possibleHsCodes` | string | No | Alternative HS codes that could apply to this item, when available.
This is provided as a stringified JSON array. Example: `["320250", "320251", "320252"]`. |
| `compliances` | object[] | No | Trade compliance data for the classified item, when compliance enrichment was
enabled. Each entry follows the same shape as the `compliance` payload returned
on the classification response. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Webhook received successfully |  |
| 201 | Webhook received and processed successfully (preferred response) |  |
| 400 | Bad request - invalid payload |  |

## Example Request

```bash
curl -X POST "https://api-sandbox.classification.avalara.net/webhook/callback" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json" \
  -d '{
  "hsClassificationId": "1234-SKU001-CA",
  "companyId": "3402",
  "itemCode": "ABC123",
  "countryOfDestination": "CA",
  "countryOfExport": "US",
  "countryOfOrigin": "CN",
  "status": "CLASSIFIED",
  "hsCode": 320250,
  "eccnCode": "5A001.a",
  "rationale": "This item is classified as a night gown based on its material composition and intended use.",
  "possibleHsCodes": "[\"320250\", \"320251\", \"320252\"]",
  "compliances": [
    {}
  ]
}'
```