> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# Replace webhook subscriptions for an agent

POST https://api.smallest.ai/atoms/v1/agent/{agentId}/webhook-subscriptions
Content-Type: application/json

**Replaces** all existing webhook subscriptions for the agent with the provided event types.
Any previously configured subscriptions for this agent are deleted before the new ones are created.
To add subscriptions without removing existing ones, retrieve current subscriptions first and include them in the request.


Reference: https://docs.smallest.ai/voice-agents/api-reference/webhooks/replace-webhook-subscriptions-for-an-agent

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: atoms
  version: 1.0.0
paths:
  /agent/{agentId}/webhook-subscriptions:
    post:
      operationId: replace-webhook-subscriptions-for-an-agent
      summary: Replace webhook subscriptions for an agent
      description: >
        **Replaces** all existing webhook subscriptions for the agent with the
        provided event types.

        Any previously configured subscriptions for this agent are deleted
        before the new ones are created.

        To add subscriptions without removing existing ones, retrieve current
        subscriptions first and include them in the request.
      tags:
        - webhooks
      parameters:
        - name: agentId
          in: path
          description: The ID of the agent to create subscriptions for
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            API key from the console ApiKey collection, sent as Bearer token.
            Also accepts session cookies for browser-based auth.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Subscriptions created successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Webhooks_replaceWebhookSubscriptionsForAnAgent_Response_201
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ReplaceWebhookSubscriptionsForAnAgentRequestNotFoundError
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventTypes:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/AgentAgentIdWebhookSubscriptionsPostRequestBodyContentApplicationJsonSchemaEventTypesItems
                  description: Array of event types to subscribe to
                webhookId:
                  type: string
                  description: The ID of the webhook to subscribe to
              required:
                - eventTypes
                - webhookId
servers:
  - url: https://api.smallest.ai/atoms/v1
    description: Production server
components:
  schemas:
    AgentAgentIdWebhookSubscriptionsPostRequestBodyContentApplicationJsonSchemaEventTypesItems:
      type: string
      enum:
        - pre-conversation
        - post-conversation
        - analytics-completed
      description: The type of event to subscribe to
      title: >-
        AgentAgentIdWebhookSubscriptionsPostRequestBodyContentApplicationJsonSchemaEventTypesItems
    Webhooks_replaceWebhookSubscriptionsForAnAgent_Response_201:
      type: object
      properties:
        status:
          type: boolean
        data:
          type: string
          description: Success message
      title: Webhooks_replaceWebhookSubscriptionsForAnAgent_Response_201
    BadRequestErrorResponse:
      type: object
      properties:
        status:
          type: boolean
        errors:
          type: array
          items:
            type: string
      title: BadRequestErrorResponse
    UnauthorizedErrorResponse:
      type: object
      properties:
        status:
          type: boolean
        errors:
          type: array
          items:
            type: string
      title: UnauthorizedErrorResponse
    ApiResponseData:
      type: object
      properties: {}
      title: ApiResponseData
    ApiResponse:
      type: object
      properties:
        status:
          type: boolean
        data:
          $ref: '#/components/schemas/ApiResponseData'
      title: ApiResponse
    ReplaceWebhookSubscriptionsForAnAgentRequestNotFoundError:
      type: object
      properties:
        status:
          type: boolean
        errors:
          type: array
          items:
            type: string
      title: ReplaceWebhookSubscriptionsForAnAgentRequestNotFoundError
    InternalServerErrorResponse:
      type: object
      properties:
        status:
          type: boolean
        errors:
          type: array
          items:
            type: string
      title: InternalServerErrorResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the console ApiKey collection, sent as Bearer token. Also
        accepts session cookies for browser-based auth.

```

## Examples



**Request**

```json
{
  "eventTypes": [
    "pre-conversation"
  ],
  "webhookId": "60d0fe4f5311236168a109ca"
}
```

**Response**

```json
{
  "status": true,
  "data": "Subscriptions created successfully"
}
```

**SDK Code**

```typescript
import { SmallestAIClient } from "smallestai";

async function main() {
    const client = new SmallestAIClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.atoms.agents.createWebhookSubscriptionsForAnAgent("agentId", {
        eventTypes: [
            "pre-conversation",
        ],
        webhookId: "60d0fe4f5311236168a109ca",
    });
}
main();

```

```python
from smallestai import SmallestAI

client = SmallestAI(
    token="YOUR_TOKEN_HERE",
)

client.atoms.webhooks.create_webhook_subscriptions_for_an_agent(
    agent_id="agentId",
    event_types=[
        "pre-conversation"
    ],
    webhook_id="60d0fe4f5311236168a109ca",
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions"

	payload := strings.NewReader("{\n  \"eventTypes\": [\n    \"pre-conversation\"\n  ],\n  \"webhookId\": \"60d0fe4f5311236168a109ca\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventTypes\": [\n    \"pre-conversation\"\n  ],\n  \"webhookId\": \"60d0fe4f5311236168a109ca\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventTypes\": [\n    \"pre-conversation\"\n  ],\n  \"webhookId\": \"60d0fe4f5311236168a109ca\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions', [
  'body' => '{
  "eventTypes": [
    "pre-conversation"
  ],
  "webhookId": "60d0fe4f5311236168a109ca"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"eventTypes\": [\n    \"pre-conversation\"\n  ],\n  \"webhookId\": \"60d0fe4f5311236168a109ca\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "eventTypes": ["pre-conversation"],
  "webhookId": "60d0fe4f5311236168a109ca"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```