Update a webhook endpoint

PATCH

/api/v1/organizations/{organizationId}/webhooks/{webhookId}

curl --request PATCH \
  --url https://api.koneth.com/api/v1/organizations/b7378db4-5a7a-4e69-a8df-04f2e6d94243/webhooks/0f6f2d88-9357-4ce6-9b9e-76db2f98bb2e \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://api.example.com/koneth/events-v2", "events": [ "position.opened", "position.closed" ] }'

• Production
• Local development

Changes where an endpoint points, what it listens for, or which server it covers. A field you leave out is left alone, so a request that edits the events cannot reset the target server by omission.

Moving the URL sends the endpoint back to pending and issues a fresh challenge, because the verification on file was answered by the address that was there before. verificationRequired says whether that happened, and deliveries stop until the endpoint verifies again. Editing the events or the server does not interrupt delivery.

Authorizations

• consoleSession

Parameters

Path Parameters

organizationId

required

string format: uuid

UUID of the organization the signed-in user belongs to.

Example

b7378db4-5a7a-4e69-a8df-04f2e6d94243

webhookId

required

string format: uuid

UUID of a webhook endpoint in the organization.

Example

0f6f2d88-9357-4ce6-9b9e-76db2f98bb2e

Request Body^required

Media typeapplication/json

object

>= 1 properties

name

string

>= 2 characters <= 80 characters

url

HTTPS address that receives the deliveries. Changing it sends the endpoint back to pending for a fresh challenge.

string format: uri

events

Array<string>

>= 1 items

Allowed values: position.opened position.closed position.reduced finance.transaction.completed account.metrics.updated

serverId

Deliver only this server’s events, or null for every server in the organization.

string | null format: uuid

Example

{
  "url": "https://api.example.com/koneth/events-v2",
  "events": [
    "position.opened",
    "position.closed"
  ]
}

Responses

200

Endpoint updated.

Media typeapplication/json

object

endpoint

required

object

id

required

string format: uuid

name

required

string

url

required

string format: uri

events

required

Array<string>

Allowed values: position.opened position.closed position.reduced finance.transaction.completed account.metrics.updated

serverId

string | null format: uuid

status

required

string

Allowed values: pending active disabled

verificationRequired

required

True when the URL moved and the endpoint has to answer a fresh challenge before it receives anything again.

boolean

Example

{
  "endpoint": {
    "id": "0f6f2d88-9357-4ce6-9b9e-76db2f98bb2e",
    "name": "api.example.com",
    "url": "https://api.example.com/koneth/events-v2",
    "events": [
      "position.opened",
      "position.closed"
    ],
    "serverId": null,
    "status": "pending",
    "verificationRequired": true
  }
}

400

Invalid request.

Media typeapplication/json

object

error

required

string

issues

Validation issue details when the request fails schema validation.

Array<object>

object

key

additional properties

any

Example^generated

{
  "error": "example",
  "issues": [
    {}
  ]
}

401

The Console session is missing or expired.

Media typeapplication/json

object

error

required

string

issues

Validation issue details when the request fails schema validation.

Array<object>

object

key

additional properties

any

Example

{
  "error": "Authentication required"
}

403

The signed-in user is not an organization Owner or Finance member.

Media typeapplication/json

object

error

required

string

issues

Validation issue details when the request fails schema validation.

Array<object>

object

key

additional properties

any

Example

{
  "error": "Insufficient organization permission"
}

404

The requested resource was not found.

Media typeapplication/json

object

error

required

string

issues

Validation issue details when the request fails schema validation.

Array<object>

object

key

additional properties

any

Example^generated

{
  "error": "example",
  "issues": [
    {}
  ]
}

500

Unexpected server error.

Media typeapplication/json

object

error

required

string

issues

Validation issue details when the request fails schema validation.

Array<object>

object

key

additional properties

any

Example

{
  "error": "Internal server error"
}