Create a webhook endpoint

POST

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

curl --request POST \
  --url https://api.koneth.com/api/v1/organizations/b7378db4-5a7a-4e69-a8df-04f2e6d94243/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "api.example.com", "url": "https://api.example.com/koneth/events", "events": [ "position.opened", "position.closed", "finance.transaction.completed" ], "serverId": null }'

• Production
• Local development

Registers an HTTPS receiver. The endpoint is created pending and receives no events until it answers the verification challenge, which is sent when Verify is clicked in Console.

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

Request Body^required

Media typeapplication/json

object

name

required

Label for the endpoint, usually the receiver host.

string

>= 2 characters <= 80 characters

url

required

HTTPS address that receives the deliveries.

string format: uri

events

required

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. Omit or send null to receive events from every server in the organization.

string | null format: uuid

Example

{
  "name": "api.example.com",
  "url": "https://api.example.com/koneth/events",
  "events": [
    "position.opened",
    "position.closed",
    "finance.transaction.completed"
  ],
  "serverId": null
}

Responses

201

Endpoint created in the pending state.

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

secret

required

Signing secret for this endpoint. It is not returned again after this response.

string

verificationToken

required

Challenge value your receiver must echo to activate the endpoint.

string

Example

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

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"
}