Skip to main content
POST
/
v1
/
partner
/
webhooks
Register a webhook
curl --request POST \
  --url https://api.hypermid.io/v1/partner/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "<string>",
  "events": [
    "swap.completed"
  ]
}
'
{
  "data": {
    "id": "whk_abc123def456",
    "url": "https://yourapp.com/webhooks/hypermid",
    "events": ["swap.completed", "swap.failed", "onramp.completed"],
    "secret": "whsec_generated_or_provided_secret",
    "active": true,
    "createdAt": "2024-03-25T10:30:00Z"
  },
  "error": null,
  "meta": {
    "requestId": "z6c7d8e9-f0a1-2345-9012-456789012345",
    "timestamp": 1711234584,
    "rateLimit": {
      "limit": 2000,
      "remaining": 1974,
      "reset": 1711234627
    }
  }
}
Creates a new webhook endpoint to receive real-time notifications for swap and on-ramp events. Requires a valid API key.
​
url
string
required
The HTTPS URL to receive webhook payloads.
​
events
string[]
required
List of event types to subscribe to. See Webhooks Guide for available events.
​
secret
string
A signing secret for HMAC-SHA256 signature verification. If not provided, one will be generated.
{
  "data": {
    "id": "whk_abc123def456",
    "url": "https://yourapp.com/webhooks/hypermid",
    "events": ["swap.completed", "swap.failed", "onramp.completed"],
    "secret": "whsec_generated_or_provided_secret",
    "active": true,
    "createdAt": "2024-03-25T10:30:00Z"
  },
  "error": null,
  "meta": {
    "requestId": "z6c7d8e9-f0a1-2345-9012-456789012345",
    "timestamp": 1711234584,
    "rateLimit": {
      "limit": 2000,
      "remaining": 1974,
      "reset": 1711234627
    }
  }
}

const webhook = await client.createWebhook({
  url: "https://yourapp.com/webhooks/hypermid",
  events: ["swap.completed", "swap.failed", "onramp.completed", "onramp.failed"],
  secret: "whsec_my_signing_secret",
});

console.log("Webhook ID:", webhook.data.id);
console.log("Secret:", webhook.data.secret);
Store the webhook secret securely. You will need it to verify webhook signatures. If you lose it, delete the webhook and create a new one.

Authorizations

​
X-API-Key
string
header
required

Partner API key. Optional for public endpoints, required for /v1/partner/*.

Body

application/json
​
url
string<uri>
required

Must use HTTPS

​
events
enum<string>[]
Available options:
swap.completed,
onramp.completed

Response

Webhook created

​
data
object
required

Response payload (null on error)

​
error
object
required
​
meta
object
required