# Configuration (/webhooks/configuration)





Each organization has one webhook destination and one active signing secret. Configure it in the Platform or from your server.

| Detail         | Value                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------- |
| Base URL       | `https://api.sandbox.tapaya.com` for sandbox, `https://api.tapaya.com` for production       |
| Authentication | Server Secret Token in `Authorization`. See [Authentication](/platform-api#authentication). |
| Scope          | One destination per organization                                                            |
| Related guide  | [Verify and Test](/webhooks/receiving)                                                      |

## Configure in the Platform [#configure-in-the-platform]

Open [API Keys](https://platform.tapaya.com/api-keys/) for your organization and find **Webhooks**.

1. Enter your public HTTPS URL.
2. Choose the events you need, or turn on **Subscribe to all webhook types**.
3. Turn on **Enable** and click **Save**.
4. Copy the signing secret and store it on your server.
5. Send a [test webhook](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="The signing secret is shown once">
  Copy it when you create or rotate the destination; it cannot be retrieved later. It only verifies incoming webhooks. Your Server Secret Token authorizes configuration requests.
</Callout>

## All operations [#all-operations]

| Operation                                     | Use it to                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| [Save a destination](#save-a-destination)     | Create or replace the current subscription, or rotate its signing secret. |
| [Read a destination](#read-a-destination)     | Retrieve the current URL, subscription mode, and enabled state.           |
| [Delete a destination](#delete-a-destination) | Remove the subscription and its delivery queue and history.               |

## Manage the destination [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Save a destination" id="save-a-destination">
    **Use it to** connect your HTTPS receiver and choose the events to deliver.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Good to know:**

    * This replaces the saved configuration; it does not add a second endpoint.
    * Creation and explicit rotation return `{"signingSecret":"twhsec_..."}`. An ordinary update returns `{"signingSecret":null}`.
    * Save the full returned secret, including its prefix. It is never returned by GET.
    * Your token decides the organization; do not send an organization ID.

    **Parameters:**

    | Field                    | Required | Meaning                                                                                                   |
    | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
    | `url`                    | Yes      | Public HTTPS URL on port 443, up to 2,048 characters, without embedded credentials or a fragment.         |
    | `eventTypes`             | Yes      | Array of names from the [catalog](/webhooks/events). Choose at least one unless subscribing to all types. |
    | `subscribeAllEventTypes` | No       | Defaults to `false`. Set `true` with `eventTypes: []` to include all current and future supported types.  |
    | `enabled`                | Yes      | Capture new matching events and send queued events when `true`.                                           |
    | `rotateSecret`           | Yes      | Generate and return a new signing secret when `true`.                                                     |
  </Accordion>

  <Accordion title="Read a destination" id="read-a-destination">
    **Use it to** inspect the saved subscription without revealing its signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Good to know:**

    * GET returns `404` when this organization has no destination.
    * All-types subscriptions return an empty `eventTypes` array with `subscribeAllEventTypes: true`.
    * The response never includes the signing secret.
    * Use `availableEventTypes` to build an event picker without hardcoding the catalog.

    **Returns:**

    | Field                    | Meaning                                                      |
    | ------------------------ | ------------------------------------------------------------ |
    | `url`                    | Saved HTTPS destination.                                     |
    | `eventTypes`             | Explicit subscriptions, or an empty array in all-types mode. |
    | `subscribeAllEventTypes` | Whether current and future supported types are selected.     |
    | `enabled`                | Whether webhooks are enabled.                                |
    | `availableEventTypes`    | Every event name you can subscribe to.                       |
  </Accordion>

  <Accordion title="Delete a destination" id="delete-a-destination">
    **Use it to** disconnect the organization and remove its queued deliveries and delivery history.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Good to know:**

    * Success returns HTTP `204` without a response body.
    * A request already in flight can still arrive after deletion.
    * Recreating the destination generates a new signing secret and does not restore deleted events.
  </Accordion>
</Accordions>

## Destination rules [#configuration]

### Changing settings [#configuration-changes]

| When you                          | What happens                                                                                                                                    |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Change the URL, events, or secret | New events use the new settings. Queued events keep the old URL and secret, so keep both working until the queue drains.                        |
| Disable webhooks                  | Queued deliveries pause and no new events are captured. Re-enabling resumes the queue, but missed changes are not backfilled. Tests still work. |
| Delete the destination            | Queued events and delivery history are removed. A request already in flight can still arrive. Recreating it creates a new signing secret.       |

### URL requirements [#destination-requirements]

* Public HTTPS on port 443. Localhost and private networks are rejected, and DNS is checked again on each connection.
* No embedded credentials, no fragment, and no redirects.
* No custom authorization headers. Verify the Tapaya signature instead, or put a server-side adapter in front of a URL that needs its own key.

## Errors [#errors]

Configuration requests fail with these responses. A receiver that rejects or misses a delivery is a different problem; see [Handle errors](/webhooks/receiving#handle-errors).

| Response     | Meaning                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `400` on PUT | Invalid URL, unsupported event type, missing required field, or an empty explicit event selection. |
| `401`        | The Server Secret Token is missing or invalid.                                                     |
| `404` on GET | No destination exists for the authenticated organization.                                          |

Continue with [signature verification and test delivery](/webhooks/receiving).