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

# Dynamic Options Endpoint

> Fill a select field from your own server. Dodo Payments sends a signed request to your options URL. Covers the request, the signature check, the response, limits, and errors.

> [!WARNING]
>
> App settings are in development. They are not yet available in production, and details can change before release.

A `select` field with `options_url` gets its options from your server. When the merchant opens the field in the Configure tab, Dodo Payments calls your URL. Use this for lists that only your app knows, for example the projects in the merchant's account.

Test installations use `options_url_test`. If you did not set it, the call for a test installation fails with a `422` error.

## Request

Dodo Payments sends `POST` to the URL, with a JSON body.

```json theme={null}
{
  "type": "settings.options_request",
  "installation_id": "ains_123",
  "livemode": false,
  "key": "workspace",
  "query": "acm",
  "values": {
    "region": "eu"
  }
}
```

| Field | Meaning |
| - | - |
| `type` | Always `settings.options_request`. |
| `installation_id` | The installation. |
| `livemode` | `true` for a live installation. |
| `key` | The key of the select field. |
| `query` | The text that the merchant typed to search. It can be empty. |
| `values` | The other saved values of the installation. It has no secrets. |

The URL must use HTTPS on port 443, with a public host name. Dodo Payments does not follow redirects.

## Verify the signature

Dodo Payments signs the request with the [Standard Webhooks](https://www.standardwebhooks.com) scheme. It uses the webhook signing secret of your app for the mode of the installation. The headers are `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Verify them against the raw body, as for [app webhooks](https://docs.dodopayments.com/developer-resources/build-an-app.md#verify-the-signature). Reject a request that fails the check.

While you rotate the secret, the old secret stays valid for 24 hours. The request can then carry a signature for each secret.

```javascript theme={null}
import { Webhook } from 'standardwebhooks';

app.post('/dodo/options', express.raw({ type: 'application/json' }), (req, res) => {
  const wh = new Webhook(process.env.DODO_APP_WEBHOOK_SECRET);
  try {
    wh.verify(req.body, {
      'webhook-id': req.headers['webhook-id'],
      'webhook-timestamp': req.headers['webhook-timestamp'],
      'webhook-signature': req.headers['webhook-signature'],
    });
  } catch {
    return res.status(401).end();
  }
  const { key, query } = JSON.parse(req.body.toString());
  const options = lookupOptions(key, query); // your code
  res.json({ options: options.slice(0, 200) });
});
```

## Response

Reply with `200` and this JSON body.

```json theme={null}
{
  "options": [
    { "value": "ws_1", "label": "Acme workspace" },
    { "value": "ws_2", "label": "Acme staging" }
  ]
}
```

Each option has a `value` and a `label`. Filter the list with `query`.

## Limits

| Limit | Value |
| - | - |
| Items in `options` | 200 |
| Response time | 3 seconds |
| Response size | 100 KB |
| Calls for each installation | 10 each minute |
| Cache | Dodo Payments caches a result for 60 seconds. |

## Errors

If your server does not answer in time, answers with an error, or sends a body that is not valid, the merchant sees an error in the field and cannot load the options. Dodo Payments returns `422` to the dashboard if the mode has no options URL or no webhook endpoint for the app. Set `webhook_url` and `webhook_url_test` for the modes that you use, because the signing secret comes from the endpoint.


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