# Insomnia Collection
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/insomnia-collection/index.md

A pre-configured Insomnia collection is available for Ethoca Alerts for Merchants. It includes all endpoints with OAuth 1.0a authentication setup, environment variables, request/response examples, and request chaining.

*** ** * ** ***

## Downloading the Collection {#downloading-the-collection}

The collection is available for download and direct import:

**Option 1: Import via URL**

1. Open [Insomnia](https://insomnia.rest)
2. Click **Create** → **Workspace** → **Import** → **URL**
3. Enter the collection URL and click **Fetch and Import**

**Option 2: Download and Import Manually**

* Download: [ethoca-alerts-for-merchants-collection.json](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/uploads/ethoca-alerts-for-merchants-insomnia.json)
* Open Insomnia → **File** → **Import** → Select the downloaded file

*** ** * ** ***

## Environment Setup {#environment-setup}

The collection uses environment variables to store credentials and URLs. You must configure these before running requests.

### Step 1: Create an Environment {#step-1-create-an-environment}

1. In Insomnia, click **Manage Environments** (gear icon, bottom left)
2. Click **Create Environment** → Name it `Ethoca Sandbox`
3. Add the following variables:

```json
{
  "base_url": "https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants",
  "consumer_key": "YOUR_SANDBOX_CONSUMER_KEY",
  "keystore_path": "/path/to/your/sandbox.p12",
  "keystore_password": "YOUR_KEYSTORE_PASSWORD",
  "keystore_alias": "YOUR_KEY_ALIAS"
}
```

4. Click **Save** and close the environment editor

### Step 2: Duplicate for Production {#step-2-duplicate-for-production}

To create a Production environment:

1. In Insomnia, right-click the **Ethoca Sandbox** environment
2. Click **Duplicate** → Name it `Ethoca Production`
3. Update the variables:
   * `base_url`: `https://api.ethocaweb.com/ethoca/alerts/merchants`
   * `consumer_key`: Your Production consumer key
   * `keystore_path`: Path to your Production keystore
4. Click **Save**

### Step 3: Select the Environment {#step-3-select-the-environment}

1. In Insomnia, click **Manage Environments** (bottom left)
2. Click the radio button next to **Ethoca Sandbox** (or **Ethoca Production**)
3. Close the environment manager --- your selected environment is now active

*** ** * ** ***

## OAuth 1.0a Configuration {#oauth-10a-configuration}

Insomnia uses the OAuth 1.0a authentication plugin to generate signatures. Each request in the collection is pre-configured.

### Verifying OAuth Settings {#verifying-oauth-settings}

1. Open any request (for example, `GET /alerts`)
2. Click the **Auth** tab
3. Verify the **Type** is set to **OAuth 1.0a**
4. Check the following fields:
   * **Signature Method:** `RSA-SHA256`
   * **Consumer Key:** `{{consumer_key}}`
   * **Private Key Path:** `{{keystore_path}}`
   * **Private Key Passphrase:** `{{keystore_password}}`
   * **Key Alias:** `{{keystore_alias}}`

If these are not configured, manually set them using the above values.

### Generating Signatures {#generating-signatures}

When you click **Send**, Insomnia automatically generates the OAuth signature. You should see:

* `Authorization: OAuth oauth_consumer_key="...", oauth_signature_method="RSA-SHA256", oauth_signature="..."`

*** ** * ** ***

## Using the Collection {#using-the-collection}

### Retrieve Alerts (Pull API) {#retrieve-alerts-pull-api}

1. Click **Requests** → **Pull API** → **GET /alerts**
2. Click the **Query** tab and modify parameters as needed:
   * `alert_type` --- Filter by `CUSTOMERDISPUTE` or `CONFIRMEDFRAUD`
   * `from_date` --- Start date (YYYY-MM-DD)
   * `to_date` --- End date (YYYY-MM-DD)
   * `size` --- Number of results (1--1000)
3. Click **Send**
4. Review the **Response** tab for alert data

**Response Example:**

```json
{
  "alerts": [
    {
      "alertId": "ALERT_ID_12345",
      "alertType": "CUSTOMERDISPUTE",
      "transactionAmount": "100.00",
      "transactionCurrency": "USD",
      "dateSubmitted": "2024-06-23",
      "customerName": "John Doe"
    }
  ]
}
```

### Acknowledge Alerts {#acknowledge-alerts}

1. Click **Requests** → **Pull API** → **POST /alerts/acknowledges**
2. Click the **Body** tab and update the alert ID:

   ```json
   {
     "acknowledgements": [
       {
         "alertId": "ALERT_ID_FROM_PREVIOUS_RESPONSE",
         "status": "SUCCESS"
       }
     ]
   }
   ```

3. Click **Send**
4. Verify success in the response

### Submit Outcomes {#submit-outcomes}

1. Click **Requests** → **Outcome API** → **POST /outcomes**
2. Click the **Body** tab and update the alert ID and outcome:

   ```json
   {
     "outcomes": [
       {
         "alertId": "ALERT_ID_FROM_ALERTS_RESPONSE",
         "alertType": "CUSTOMERDISPUTE",
         "outcomeCodes": [
           {
             "codeType": "INVESTIGATION_RESULT",
             "code": "RESOLVED"
           }
         ]
       }
     ]
   }
   ```

3. Click **Send**
4. Verify success in the response

### Push Webhook Simulation (Testing Only) {#push-webhook-simulation-testing-only}

The collection includes a **Push Webhook** request that simulates an incoming webhook from Ethoca:

1. Click **Requests** → **Push API** → **POST /webhook (Simulation)**
2. Review the simulated webhook payload in the **Body** tab
3. Update the `POST` URL to your local webhook endpoint (for example, `http://localhost:8080/ethoca/webhook`)
4. Click **Send**
5. Verify your webhook handler processes the payload correctly

*** ** * ** ***

## Request Chaining {#request-chaining}

Insomnia supports request chaining via template tags. The collection includes pre-configured chains that automatically pass values from one request to the next.

#### Example: Retrieve Alerts → Acknowledge → Submit Outcomes {#example-retrieve-alerts--acknowledge--submit-outcomes}

1. Run **GET /alerts** --- stores `alertId` in environment
2. Run **POST /alerts/acknowledges** --- automatically uses `alertId` from previous response
3. Run **POST /outcomes** --- automatically uses `alertId` and outcome data

To use template tags:

* Click **Send Request** in the request body where you want to insert a value
* Select the template tag (for example, `Response → alerts[0].alertId`)

*** ** * ** ***

## Request History and Timeline {#request-history-and-timeline}

Insomnia automatically tracks all requests. To review past requests:

1. Click **Timeline** (left sidebar)
2. Browse all recent requests and responses
3. Click any request to view full details (headers, body, response)

This is useful for debugging and auditing integration workflows.

*** ** * ** ***

## Debugging {#debugging}

**View Sent Request Details**

When you send a request, click the **Request** tab in the response panel to see exactly what was sent to the API, including:

* Full URL with query parameters
* Headers (including OAuth signature)
* Request body

**View Response Details**

Click the **Response** tab to see:

* HTTP status code
* Response body (formatted JSON)
* Response headers
* Response time and size

*** ** * ** ***

## Troubleshooting {#troubleshooting}

**401 Unauthorized Error**

* Verify that `consumer_key`, `keystore_path`, and `keystore_password` are correct in your environment
* Confirm the keystore file exists at the specified path
* Check that you've selected the correct Environment in Insomnia

**Connection Refused**

* Confirm that `base_url` is correct for your environment (Sandbox vs. Production)
* Verify network connectivity to `sandbox.api.ethocaweb.com` or `api.ethocaweb.com`

**Empty Alert List**

* Ensure that test alerts have been submitted to Sandbox
* Verify the date range in your `GET /alerts` request covers the alert submission time

**OAuth Signature Generation Failed**

* Confirm that the keystore file path is correct and the file is readable
* Verify that the keystore password is correct
* Check that the key alias exists in the keystore

*** ** * ** ***

## Next Steps {#next-steps}

* Review [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/tutorials-and-guides/quick-start-guide.md) for integration setup
* See [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/testing/index.md) for comprehensive test scenarios
* Refer to [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/api-reference/index.md) for endpoint specifications
* Check [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/code-and-formats/index.md) for error code reference