Webhooks

Webhooks let your application receive real-time notifications when events occur within Buildmarkets — account approvals, funding transfers, order fills, and more. Rather than polling the API repeatedly to check for status changes, you register an HTTPS endpoint and Buildmarkets pushes event payloads to it as things happen. This page covers how to register and manage webhook endpoints. For a full reference of every event type and its payload structure, see Webhook Events Reference. For payload verification, retry logic, and delivery guarantees, see Webhook Security & Delivery.

How webhooks work

      Event occurs in Buildmarkets         Buildmarkets sends HTTP POST          Your server
      (e.g., order filled)   →     to your webhook URL      →    processes event
                                   with signed payload            and returns 2xx

Register an HTTPS endpoint via POST /v1/webhooks
Receive a signing secret — used to verify that payloads come from Buildmarkets
Buildmarkets delivers a JSON payload to your URL via HTTP POST whenever a subscribed event fires
Your server validates the signature, processes the event, and returns a 2xx status
Buildmarkets retries failed deliveries automatically (see Security & Delivery)

The secret is shown only once. Store it securely at registration time — it cannot be retrieved again. If lost, delete the webhook and create a new one.

Endpoints

Method	Path	Description
`POST`	`/v1/webhooks`	Register a new webhook endpoint
`GET`	`/v1/webhooks`	List all registered webhooks
`GET`	`/v1/webhooks/{webhookId}`	Get details for a specific webhook
`PATCH`	`/v1/webhooks/{webhookId}`	Update URL, events, or status
`DELETE`	`/v1/webhooks/{webhookId}`	Permanently remove a webhook
`POST`	`/v1/webhooks/{webhookId}/test`	Send a test event to verify connectivity
`GET`	`/v1/webhooks/{webhookId}/deliveries`	View delivery attempt history

Create a webhook

Registers a new HTTPS endpoint to receive events. Pass an empty events array to subscribe to all event types. Pass specific event names to subscribe to a subset.

`POST /v1/webhooks`

Request body

Field	Type	Required	Description
`url`	string (URI)	✅	HTTPS URL where Buildmarkets will POST event payloads. Must be a valid `https://` URL
`events`	array of strings	✅	Event types to subscribe to. Pass an empty array `[]` to receive all events. Must be one of the valid event types below

Valid event types

Any value in events must be one of the following. An unrecognised event name is rejected with 400.

Domain	Event	When it fires
Account	`account.kyc_approved`	KYC review passed; account is now `ACTIVE`
Account	`account.kyc_rejected`	KYC review failed; account is now `ACTION_REQUIRED`
Account	`account.closed`	Account has been successfully closed
Funding	`funding.ach_relationship_created`	An ACH relationship has been created and approved
Funding	`funding.ach_relationship_removed`	An ACH relationship has been cancelled
Funding	`funding.deposit_completed`	An ACH deposit has fully settled
Funding	`funding.deposit_returned`	An ACH deposit was returned by the bank
Funding	`funding.withdrawal_completed`	An ACH withdrawal has fully settled
Funding	`funding.withdrawal_returned`	An ACH withdrawal was returned by the bank
Trading	`order.submitted`	An order was accepted and submitted to the market
Trading	`order.filled`	An order was fully executed
Trading	`order.rejected`	An order was rejected before or during execution
Trading	`order.cancelled`	An order was cancelled (user-initiated or system)

For the full payload each event delivers, see the Webhook Events Reference.

Response body (`201 Created`)

Field	Type	Description
`id`	string (UUID)	Unique identifier for this webhook
`url`	string	The registered HTTPS endpoint
`events`	array of strings	Subscribed event types (empty = all)
`status`	string	Webhook status: `active` or `disabled`
`secret`	string	Shown only once. HMAC signing secret — store this securely immediately
`created_at`	string (ISO 8601)	Registration timestamp

⚠️ Store the secret now. It is returned exactly once in the 201 response and cannot be retrieved again. If lost, the webhook must be deleted and recreated.

curl -X POST https://api.tappengine.com/v1/webhooks \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/buildmarkets",
    "events": []
  }'

curl -X POST https://api.tappengine.com/v1/webhooks \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/buildmarkets",
    "events": [
      "account.kyc_approved",
      "account.closed",
      "funding.deposit_completed",
      "order.filled",
      "order.cancelled"
    ]
  }'

Example response

{
  "id": "wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
  "url": "https://myapp.com/webhooks/buildmarkets",
  "events": [
    "account.kyc_approved",
    "account.closed",
    "funding.deposit_completed",
    "order.filled",
    "order.cancelled"
  ],
  "status": "active",
  "secret": "whsec_xK9mP2qR7tNvL4jW8cB5yZ3hF6dE1sA0",
  "created_at": "2026-03-24T10:00:00Z"
}

List webhooks

Returns all registered webhook endpoints for your account.

`GET /v1/webhooks`

Example request

curl https://api.tappengine.com/v1/webhooks \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET"

Example response

[
  {
    "id": "wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "url": "https://myapp.com/webhooks/buildmarkets",
    "events": ["account.kyc_approved", "order.filled"],
    "status": "active",
    "created_at": "2026-03-24T10:00:00Z"
  }
]

Note: The secret field is not included in list or get responses — only in the initial 201 creation response.

Get a webhook

Returns the configuration for a single registered webhook by ID. The signing secret is not returned.

`GET /v1/webhooks/{webhookId}`

Path parameters

Parameter	Type	Required	Description
`webhookId`	string (UUID)	✅	The webhook ID

Example request

curl https://api.tappengine.com/v1/webhooks/wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6 \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET"

Update a webhook

Updates the URL, subscribed events, or status of an existing webhook. Only include fields you want to change.

`PATCH /v1/webhooks/{webhookId}`

Path parameters

Parameter	Type	Required	Description
`webhookId`	string (UUID)	✅	The webhook ID to update

Request body (all fields optional)

Field	Type	Description
`url`	string	New HTTPS URL to deliver events to
`events`	array of strings	Updated list of subscribed event types. Replaces the existing list. Same valid event types as on create
`status`	string	`active` to enable delivery, `disabled` to pause it

Example request — disable a webhook temporarily

curl -X PATCH https://api.tappengine.com/v1/webhooks/wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6 \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'

Example request — update URL and event subscriptions

curl -X PATCH https://api.tappengine.com/v1/webhooks/wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6 \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/buildmarkets-v2",
    "events": ["account.kyc_approved", "order.filled", "order.rejected", "funding.deposit_completed"]
  }'

Send a test event

Triggers a synthetic test payload to be sent to the webhook’s registered URL. Use this to verify that your endpoint is reachable and correctly processing Buildmarkets payloads without waiting for a real event to occur.

`POST /v1/webhooks/{webhookId}/test`

Path parameters

Parameter	Type	Required	Description
`webhookId`	string (UUID)	✅	The webhook ID to test

Example request

curl -X POST https://api.tappengine.com/v1/webhooks/wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6/test \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET"

Buildmarkets sends a test payload with "event_type": "webhook.test" to the registered URL. Your endpoint should respond with a 2xx status. Check the delivery history to see whether it was received successfully.

Delete a webhook

Permanently removes the webhook. Delivery to the registered URL stops immediately. This action cannot be undone.

`DELETE /v1/webhooks/{webhookId}`

Returns 204 No Content on success.

Example request

curl -X DELETE https://api.tappengine.com/v1/webhooks/wh_a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6 \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET"

Common errors

HTTP Status	Error	Cause
`400`	`INVALID_URL`	Webhook URL is not a valid `https://` URI
`400`	`INVALID_EVENT`	One or more event names in the `events` array are not recognized
`404`	`WEBHOOK_NOT_FOUND`	No webhook found for the provided `webhookId`

Next steps

Webhook Events Reference → — Full list of event types and their payload schemas
Webhook Security & Delivery → — Signature verification, retry logic, and delivery history

Updated 3 months ago

Core Concepts

Infrastructure

How webhooks work

Endpoints

Create a webhook

`POST /v1/webhooks`

Request body

Valid event types

Response body (`201 Created`)

Example response

List webhooks

`GET /v1/webhooks`

Example request

Example response

Get a webhook

`GET /v1/webhooks/{webhookId}`

Path parameters

Example request

Update a webhook

`PATCH /v1/webhooks/{webhookId}`

Path parameters

Request body (all fields optional)

Example request — disable a webhook temporarily

Example request — update URL and event subscriptions

Send a test event

`POST /v1/webhooks/{webhookId}/test`

Path parameters

Example request

Delete a webhook

`DELETE /v1/webhooks/{webhookId}`

Example request

Common errors

Next steps

​How webhooks work

​Endpoints

​Create a webhook

​POST /v1/webhooks

​Request body

​Valid event types

​Response body (201 Created)

​Example request — subscribe to all events

​Example request — subscribe to specific events

​Example response

​List webhooks

​GET /v1/webhooks

​Example request

​Example response

​Get a webhook

​GET /v1/webhooks/{webhookId}

​Path parameters

​Example request

​Update a webhook

​PATCH /v1/webhooks/{webhookId}

​Path parameters

​Request body (all fields optional)

​Example request — disable a webhook temporarily

​Example request — update URL and event subscriptions

​Send a test event

​POST /v1/webhooks/{webhookId}/test

​Path parameters

​Example request

​Delete a webhook

​DELETE /v1/webhooks/{webhookId}

​Example request

​Common errors

​Next steps

How webhooks work

Endpoints

Create a webhook

`POST /v1/webhooks`

Request body

Valid event types

Response body (`201 Created`)

Example request — subscribe to all events

Example request — subscribe to specific events

Example response

List webhooks

`GET /v1/webhooks`

Example request

Example response

Get a webhook

`GET /v1/webhooks/{webhookId}`

Path parameters

Example request

Update a webhook

`PATCH /v1/webhooks/{webhookId}`

Path parameters

Request body (all fields optional)

Example request — disable a webhook temporarily

Example request — update URL and event subscriptions

Send a test event

`POST /v1/webhooks/{webhookId}/test`

Path parameters

Example request

Delete a webhook

`DELETE /v1/webhooks/{webhookId}`

Example request

Common errors

Next steps