---
title: "Create legacy merchant webhooks"
method: POST
path: "/webhook/v3/config"
tags: ["Webhook Service"]
---

# Create legacy merchant webhooks

`POST /webhook/v3/config`

Configures webhooks using the legacy workflow, including the URLs a merchant's webhooks are sent to and the event types which trigger webhooks.

If you need to whitelist the IP addresses that send the webhooks, you can find the list for both sandbox and production environments at [https://ip-ranges.nex.io/ip-ranges.json](https://ip-ranges.nex.io/ip-ranges.json).

For a tutorial about configuring and using webhooks, see [Configuring webhooks](https://docs.nexiopay.com/docs/configuring-legacy-webhooks) in Guides.

<!-- theme: info -->
> 📘 Note
> 
> For the current workflow, see the [Register webhook URLs](https://docs.nexiopay.com/reference/registerwebhookurls) endpoint instead.

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you must use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).


<!-- theme: warning -->
> 🛑 Important 
> 
> Nexio supports only either the new webhooks or these legacy ones. Before configuring URLs for legacy webhooks, ensure that you do not have any URLS for the new ones configured: [View webhook URLs by ID and type](https://docs.nexiopay.com/reference/viewwebhookurlsbyidandtype).
> 
> If you need to remove one or more (or all) legacy webhooks, use this endpoint, but send an empty `webhooks` object to remove all or, to remove just one, send all current configured webhooks minus the object that corresponds to the event type for the webhook you want to remove. For additional information, see [Deregistering legacy webhooks](https://docs.nexiopay.com/docs/) in Guides.


<div style="display:none;">

## Request parameters
- merchantId
- payoutAccountId
- webhooks
- webhooks.ACCOUNT_UPDATER_ACCOUNT_CLOSED
- webhooks.ACCOUNT_UPDATER_ACCOUNT_CLOSED.url
- webhooks.ACCOUNT_UPDATER_CONTACT_CARDHOLDER
- webhooks.ACCOUNT_UPDATER_CONTACT_CARDHOLDER.url
- webhooks.CARD_DATA_UPDATED
- webhooks.CARD_DATA_UPDATED.url
- webhooks.CARD_SAVED
- webhooks.CARD_SAVED.url
- webhooks.ECHECK_SAVED
- webhooks.ECHECK_SAVED.url
- webhooks.SUBSCRIPTION_DETAILS
- webhooks.SUBSCRIPTION_DETAILS.url
- webhooks.TRANSACTION_AUTHORIZED
- webhooks.TRANSACTION_AUTHORIZED.url
- webhooks.TRANSACTION_CAPTURED
- webhooks.TRANSACTION_CAPTURED.url
- webhooks.TRANSACTION_PENDING
- webhooks.TRANSACTION_PENDING.url
- webhooks.TRANSACTION_REFUNDED
- webhooks.TRANSACTION_REFUNDED.url
- webhooks.TRANSACTION_SETTLED
- webhooks.TRANSACTION_SETTLED.url
- webhooks.TRANSACTION_VOIDED
- webhooks.TRANSACTION_VOIDED.url
- webhooks.PAYOUT
- webhooks.PAYOUT.url
- webhooks.SPENDBACK
- webhooks.SPENDBACK.url


## Response parameters
- merchantId
- payoutAccountId
- webhooks
- webhooks.ACCOUNT_UPDATER_ACCOUNT_CLOSED
- webhooks.ACCOUNT_UPDATER_ACCOUNT_CLOSED.url
- webhooks.ACCOUNT_UPDATER_CONTACT_CARDHOLDER
- webhooks.ACCOUNT_UPDATER_CONTACT_CARDHOLDER.url
- webhooks.CARD_DATA_UPDATED
- webhooks.CARD_DATA_UPDATED.url
- webhooks.CARD_SAVED
- webhooks.CARD_SAVED.url
- webhooks.ECHECK_SAVED
- webhooks.ECHECK_SAVED.url
- webhooks.SUBSCRIPTION_DETAILS
- webhooks.SUBSCRIPTION_DETAILS.url
- webhooks.TRANSACTION_AUTHORIZED
- webhooks.TRANSACTION_AUTHORIZED.url
- webhooks.TRANSACTION_CAPTURED
- webhooks.TRANSACTION_CAPTURED.url
- webhooks.TRANSACTION_PENDING
- webhooks.TRANSACTION_PENDING.url
- webhooks.TRANSACTION_REFUNDED
- webhooks.TRANSACTION_REFUNDED.url
- webhooks.TRANSACTION_SETTLED
- webhooks.TRANSACTION_SETTLED.url
- webhooks.TRANSACTION_VOIDED
- webhooks.TRANSACTION_VOIDED.url
- webhooks.PAYOUT
- webhooks.PAYOUT.url
- webhooks.SPENDBACK
- webhooks.SPENDBACK.url
- dateCreated
- dateLastModified

</div>

## Request body

- union
  - object — When registering one or more webhooks for a `merchantId`, you must specify the `merchantId` as well as at least one webhook type in the `webhooks` object.
    - `merchantId` string, required — The Nexio merchant ID to register the webhook URL for. The ID parameter name to use is `merchantId`. Either this parameter or `payoutAccountId` is required.
    - `webhooks` object, required — An object containing the webhook URL. See the [event types](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) table to see a possible list of keys.
      - `ACCOUNT_UPDATER_ACCOUNT_CLOSED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `ACCOUNT_UPDATER_CONTACT_CARDHOLDER` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `CARD_DATA_UPDATED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `CARD_SAVED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `ECHECK_SAVED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `SUBSCRIPTION_DETAILS` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `TRANSACTION_AUTHORIZED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string
      - `TRANSACTION_CAPTURED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string
      - `TRANSACTION_PENDING` object
        - `url` string
      - `TRANSACTION_REFUNDED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string
      - `TRANSACTION_SETTLED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string
      - `TRANSACTION_VOIDED` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string
  - object — When registering one or more webhooks for a `payoutAccountId`, you must specify the `payoutAccountId` as well as at least one webhook type in the `webhooks` object.
    - `payoutAccountId` string, required — The Nexio ID for the payout account. The ID parameter name to use is `payoutAccountId`. Either this parameter or `merchantId` is required.
    - `webhooks` object, required — An object containing the webhook URL. See the [event types](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) table to see a possible list of keys.
      - `PAYOUT` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.
      - `SPENDBACK` object — The [event type](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types) to register the webhook for.
        - `url` string — The URL the webhook is sent to.

## Response `200`

Success

- object
  - `merchantId` string — The Nexio merchant ID associated with the webhooks. This parameter is only returned when the request included the `merchantId` parameter. Either this parameter or `payoutAccountId` is returned.
  - `payoutAccountId` string — The Nexio ID for the payout account associated with the webhooks. This parameter is only returned when the request included the `payoutAccountId` parameter. Either this parameter or `merchantId` is returned.
  - `webhooks` object — A list of all the webhooks currently configured. Keys are the [webhook event types](https://docs.nexiopay.com/docs/legacy-webhooks-and-event-types#event-types).
    - `ACCOUNT_UPDATER_ACCOUNT_CLOSED` object — Webhook will be sent when the account associated with the card has been closed.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `ACCOUNT_UPDATER_CONTACT_CARDHOLDER` object — Webhook will be sent when the card brand advises you to contact the cardholder.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `CARD_DATA_UPDATED` object — Webhook will be sent when card data has been updated.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `CARD_SAVED` object — Webhook will be sent when card data has been saved.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `ECHECK_SAVED` object — Webhook will be sent when echeck data has been saved.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `PAYOUT` object — Webhook will be sent when a payout gets submitted (**Note:** This means that you will receive multiple webhooks when submitting a batch payout), a [payout status](https://docs.nexiopay.com/docs/constant-payouts-values#payout-status-payoutstatus) changes, or a [transfer status](https://docs.nexiopay.com/docs/constant-payouts-values#transfer-status-transferstatus) changes.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `SPENDBACK` object — Webhook will be sent when a spendback is submitted, a spendback is refunded, or a spendback status](doc:constant-payouts-values#spendback-status-spendbackstatus) changes.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `SUBSCRIPTION_DETAILS` object — Webhook will be sent when a subscription has been processed.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `TRANSACTION_AUTHORIZED` object — Webhook will be sent when a transaction is authorized.
      - `url` string — The URL the webhook will be sent to when a transaction has been authorized.
    - `TRANSACTION_CAPTURED` object — Webhook will be sent when a transaction is captured.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `TRANSACTION_PENDING` object — Webhook will be sent when a transaction is marked as pending.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `TRANSACTION_REFUNDED` object — Webhook will be sent when a transaction is refunded.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `TRANSACTION_SETTLED` object — Webhook will be sent when a transaction is settled.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
    - `TRANSACTION_VOIDED` object — Webhook will be sent when a transaction is voided.
      - `url` string — The URL the webhook will be sent to when a transaction has been captured.
  - `dateCreated` string — The date and time the configuration was created, formatted as an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC.
  - `dateLastModified` string — The date and time the configuration was last modified, formatted as an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)