---
title: "Add / delete / test a webhook (API Pro and above)"
method: POST
path: "/api/bot/v1/webhooks"
tags: ["Paper trading"]
---

# Add / delete / test a webhook (API Pro and above)

`POST /api/bot/v1/webhooks`

## Request

- Base URL: `https://marginpad.io`
- URL: `https://marginpad.io/api/bot/v1/webhooks`
- Auth: API key in header `X-API-Key`

act:"add" {url, events?} registers an https URL (max 3 per account) and returns its secret once. act:"delete" {id}. act:"test" {id} delivers a ping right now and returns the HTTP status your server answered. Deliveries: POST JSON {event, ts, hook_id, data} with headers X-MP-Event, X-MP-Delivery, X-MP-Timestamp and X-MP-Signature = sha256=HMAC_SHA256(secret, raw body). Retried 5 times with backoff; paused after 25 consecutive failures.

## Request body

- WebhookRequest
  - `act` 'add' | 'delete' | 'test', required
  - `url` string: add: https URL on a public host
  - `events` string[]: add: subset to receive; omit for all
  - `id` string: delete / test: the webhook id

## Response `200`

ok

## Other responses

- `400`: bad_url / bad_event
- `402`: Premium required
- `409`: too_many_webhooks

---

[API](https://skmtc.dev/marginpad/apis/marginpad-free-crypto-api.md) · [All operations](https://skmtc.dev/marginpad/apis/marginpad-free-crypto-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marginpad/apis/marginpad-free-crypto-api/revisions/27d21fcd0bf0?raw)