Register webhooks

POST /api/user/register-webhooks

Replace your account's webhook set. The request body is a top-level JSON array of webhook registrations - each registration names a URL, an authentication style (none, bearer, basic, or api-key), and an optional secret (required whenever authType is not none). On every transaction status change, each enabled webhook receives a POST whose body is the TxNotification object. The response is a bare object - not wrapped in the success envelope - echoing the stored webhooks with all secrets omitted. Authenticate with either an api-key header or an Authorization Bearer JWT.

Authentication

Send your API key in the api-key header.

Request body (application/json)

[
  {
    "url": "https://api.example.org/hooks/photon",
    "authType": "bearer",
    "secret": "whsec_9f2c4e6a8b0d2f4a6c8e0b2d",
    "enabled": true
  },
  {
    "url": "https://ops.example.org/photon-events",
    "authType": "api-key",
    "secret": "hk_1a3c5e7b9d0f2a4c",
    "apiKeyVar": "x-hook-key",
    "apiKeyPlacement": "header",
    "enabled": true
  }
]

Responses

Status	Description
200	Webhooks stored. The response is a bare object (no success envelope); secret values are never echoed back.
400	Invalid registration. Plausible codes: VALIDATION_001 (URL does not start with http:// or https://, unknown authType, or a non-none authType without a secret).
401	Authentication failed. Plausible codes: AUTH_001 (no credentials supplied), AUTH_002 (invalid API key), AUTH_004 (invalid JWT), AUTH_005 (expired JWT).
500	Server error. Plausible codes: SYSTEM_001.

200 response

{
  "userId": "68c275846a6ba1c9a2198a8c",
  "address": "0xa7a833e6641d7901f30ead6f27d4ee2c9bb670a7",
  "webhooks": [
    {
      "url": "https://api.example.org/hooks/photon",
      "authType": "bearer",
      "enabled": true
    },
    {
      "url": "https://ops.example.org/photon-events",
      "authType": "api-key",
      "apiKeyVar": "x-hook-key",
      "apiKeyPlacement": "header",
      "enabled": true
    }
  ]
}

400 response

{
  "success": false,
  "error": {
    "code": "VALIDATION_001",
    "message": "authType bearer requires `secret`",
    "category": "VALIDATION",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

401 response

{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "message": "Unauthorized access",
    "category": "AUTH",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

500 response

{
  "success": false,
  "error": {
    "code": "SYSTEM_001",
    "message": "Database operation failed",
    "category": "SYSTEM",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}