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

# Add Webhook

> Register a new webhook endpoint for transaction events

<Note>
  **Auth method: Signed (HMAC)** — this endpoint requires the full set of signed
  headers: `x-access-id`, `x-request-id`, `x-timestamp`, and an HMAC-SHA256
  `authorization` signature. See [Authentication](/api-reference/authentication#signed-hmac-authentication).
</Note>

## Headers

<ParamField header="authorization" type="string" required>
  Base64-encoded HMAC-SHA256 signature of the request payload using the API secret

  **Minimum string length:** `1`

  **Example:** `"5e73d044c44d733fcf819ad3409aaaddca840d421b69cb0b04e2c750fc62e-ce7526d36296237663ad1f06f62a730c0466516507196b3ce6567493c-c52a7cf63d"`
</ParamField>

<ParamField header="x-timestamp" type="string" required>
  Current timestamp in ISO 8601 format

  **Example:** `"2025-03-15T09:45:53.000Z"`
</ParamField>

<ParamField header="x-request-id" type="string" required>
  Unique identifier for the request (UUID v4)

  **Example:** `"550e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField header="x-access-id" type="string" required>
  Your API access ID provided by Tender

  **Example:** `"your-access-id-here"`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Media type of the request body

  **Example:** `"application/json"`
</ParamField>

## Body

<ParamField body="url" type="string" required>
  Webhook endpoint URL to receive event notifications

  **Example:** `"https://example.com/webhook"`
</ParamField>

<ParamField body="description" type="string">
  Description of the webhook purpose

  **Example:** `"Transaction notifications"`
</ParamField>

<ParamField body="eventTypes" type="array" required>
  Array of event types to subscribe to

  **Example:** `["transaction_completed"]`
</ParamField>

<ParamField body="headers" type="object">
  Custom headers to include in webhook requests (optional)

  **Example:** `{ "api-key": "your-api-key" }`
</ParamField>

## Response

<ResponseField name="status" type="string" required>
  Status of the API request

  **Example:** `"success"`
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable message describing the result

  **Example:** `"success"`
</ResponseField>

<ResponseField name="data" type="object" required>
  The created webhook configuration

  <Expandable title="data properties">
    <ResponseField name="_id" type="string">
      Unique MongoDB identifier for the webhook

      **Example:** `"691069ff947a702cfad9e861"`
    </ResponseField>

    <ResponseField name="merchantId" type="string">
      Merchant ID associated with the webhook

      **Example:** `"6538e8f9bdec6d1a21978a64"`
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the webhook

      **Example:** `"new example webhooks"`
    </ResponseField>

    <ResponseField name="url" type="string">
      Webhook endpoint URL

      **Example:** `"https://exampleiop.com"`
    </ResponseField>

    <ResponseField name="eventTypes" type="array">
      Array of subscribed event types

      **Example:** `["transaction_completed"]`
    </ResponseField>

    <ResponseField name="headers" type="object">
      Custom headers for webhook requests

      **Example:** `{ "api-key": "allow-requior" }`
    </ResponseField>

    <ResponseField name="isActive" type="boolean">
      Whether the webhook is currently active

      **Example:** `true`
    </ResponseField>

    <ResponseField name="isDeleted" type="boolean">
      Whether the webhook has been deleted

      **Example:** `false`
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the webhook was created

      **Example:** `"2025-11-09T10:16:31.594Z"`
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the webhook was last updated

      **Example:** `"2025-11-09T10:18:35.286Z"`
    </ResponseField>

    <ResponseField name="__v" type="number">
      Version key for MongoDB document

      **Example:** `0`
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml POST /v1/api/webhook
openapi: 3.1.0
info:
  title: Tender API
  description: Tender Developer API for cryptocurrency payments and agent management
  version: 1.0.0
  contact:
    name: Tender Support
    url: https://tender.cash
servers:
  - url: https://secureapi.tender.cash
    description: Production Server
  - url: https://sandbox-api.tender.cash
    description: Sandbox Server
security:
  - SignedAuth: []
tags:
  - name: Agents
    description: Manage agents and sub-businesses
  - name: Transactions
    description: Payment and transaction operations
  - name: System
    description: System information and configuration
  - name: Webhooks
    description: Webhook management and logs
  - name: On-ramp
    description: Fiat-to-crypto on-ramp operations
  - name: Payouts
    description: Send crypto from merchant balance to a wallet address or payout account
  - name: Subwallets
    description: Provision and manage crypto wallet infrastructure for your end-users
paths:
  /v1/api/webhook:
    post:
      tags:
        - Webhooks
      summary: Add Webhook
      description: Register a new webhook endpoint
      operationId: addWebhook
      parameters:
        - name: authorization
          in: header
          required: true
          description: >-
            Base64-encoded HMAC-SHA256 signature of the request payload using
            the API secret
          schema:
            type: string
        - name: x-timestamp
          in: header
          required: true
          description: Current timestamp in ISO 8601 format
          schema:
            type: string
            format: date-time
          example: '2025-03-15T09:45:53.000Z'
        - name: x-request-id
          in: header
          required: true
          description: Unique identifier for the request (UUID v4)
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-access-id
          in: header
          required: true
          description: Your API access ID provided by Tender
          schema:
            type: string
          example: your-access-id-here
        - name: Content-Type
          in: header
          required: true
          description: Media type of the request body
          schema:
            type: string
          example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddWebhookRequest'
            example:
              url: https://example.com/webhook
              description: Transaction notifications
              eventTypes:
                - transaction_completed
              headers:
                api-key: your-api-key
      responses:
        '200':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
      security:
        - SignedAuth: []
components:
  schemas:
    AddWebhookRequest:
      type: object
      required:
        - url
        - eventTypes
      properties:
        url:
          type: string
          format: uri
          description: Webhook endpoint URL
          example: https://example.com
        description:
          type: string
          description: Description of the webhook
          example: Transaction notifications
        eventTypes:
          type: array
          items:
            type: string
          description: Event types to subscribe to
          example:
            - transaction_completed
        headers:
          type: object
          description: Custom headers to include in webhook requests
          example:
            api-key: your-api-key
    WebhookResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            _id:
              type: string
            merchantId:
              type: string
            description:
              type: string
            url:
              type: string
            eventTypes:
              type: array
              items:
                type: string
            headers:
              type: object
            isActive:
              type: boolean
            isDeleted:
              type: boolean
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
  securitySchemes:
    SignedAuth:
      type: apiKey
      in: header
      name: authorization
      description: >-
        Signed (HMAC) authentication. Required headers: x-access-id,
        x-request-id (UUID v4), x-timestamp (ISO 8601), and authorization
        (Base64 HMAC-SHA256 signature of {timeStamp, requestId, accessId} using
        your access secret).

````