> 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/api-reference/voice-agents/webhooks/replace-webhook-subscriptions-for-an-agent

## Authentication

- `Authorization` header (bearer token, required) — API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

## Request

### Path parameters

- `agentId` (string, required) — The ID of the agent to create subscriptions for

### Body (application/json)

This endpoint expects an object.

- `eventTypes` (list of enum, required) — Array of event types to subscribe to
  - Allowed values: `pre-conversation`, `post-conversation`, `analytics-completed`
- `webhookId` (string, required) — The ID of the webhook to subscribe to

## Response

### 201

Subscriptions created successfully

- `status` (boolean, optional)
- `data` (string, optional) — Success message

## Errors

### 400 Bad Request Error

Invalid input

- `status` (boolean, optional)
- `errors` (list of string, optional)

### 401 Unauthorized Error

Unauthorized access

- `status` (boolean, optional)
- `errors` (list of string, optional)

### 403 Forbidden Error

Forbidden access

- `status` (boolean, optional)
- `data` (ApiResponseData, optional)

### 404 Not Found Error

Agent not found

- `status` (boolean, optional)
- `errors` (list of string, optional)

### 500 Internal Server Error

Internal server error

- `status` (boolean, optional)
- `errors` (list of string, optional)

## Types

### ApiResponseData

## Examples

**Request**

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

**Response**

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

**SDK Code**

```python
import requests

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

payload = {
    "eventTypes": ["pre-conversation"],
    "webhookId": "60d0fe4f5311236168a109ca"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.smallest.ai/atoms/v1/agent/agentId/webhook-subscriptions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"eventTypes":["pre-conversation"],"webhookId":"60d0fe4f5311236168a109ca"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```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()
```