> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Webhook

> Register a new webhook endpoint to receive stock token events

Registers a new webhook partner for the authenticated instance. Returns an API key and webhook secret used to authenticate incoming webhook deliveries. The webhook URL must use HTTPS.

## Request Body

<ParamField body="name" type="string" required>
  Display name for this webhook integration. Maximum 100 characters.
</ParamField>

<ParamField body="webhookUrl" type="string" required>
  HTTPS URL where events will be delivered.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">Request status.</ResponseField>

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="id" type="string">Partner ID.</ResponseField>
    <ResponseField name="name" type="string">Display name.</ResponseField>
    <ResponseField name="apiKey" type="string">API key for authenticating webhook requests.</ResponseField>
    <ResponseField name="webhookSecret" type="string">Secret used to verify webhook signatures. Store this securely.</ResponseField>
    <ResponseField name="webhookUrl" type="string">Registered delivery URL.</ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  The `apiKey` and `webhookSecret` are only returned once at registration time. Store them securely.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.trusset.org/stocks/api/webhooks/register" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: trusset_abc123xy_secret..." \
    -d '{
      "name": "Settlement System",
      "webhookUrl": "https://api.example.com/webhooks/trusset"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://api.trusset.org/stocks/api/webhooks/register',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'trusset_abc123xy_secret...'
      },
      body: JSON.stringify({
        name: 'Settlement System',
        webhookUrl: 'https://api.example.com/webhooks/trusset'
      })
    }
  );
  const { data } = await response.json();
  // Store data.apiKey and data.webhookSecret securely
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "wh_abc123",
      "name": "Settlement System",
      "apiKey": "whk_live_...",
      "webhookSecret": "whs_live_...",
      "webhookUrl": "https://api.example.com/webhooks/trusset"
    },
    "metadata": {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2025-06-15T12:00:00.000Z",
      "instanceId": "inst_abc123"
    }
  }
  ```

  ```json Error - Invalid URL theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_URL",
      "message": "webhookUrl must use HTTPS"
    },
    "metadata": {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2025-06-15T12:00:00.000Z",
      "instanceId": "inst_abc123"
    }
  }
  ```
</ResponseExample>