Conduits - API Reference | Twitch Developers

Get Conduits

Gets the conduits for a client ID.

Endpoint

GEThttps://api.twitch.tv/helix/eventsub/conduits

Authorization

Requires one of the following:

An app access token.

Response Body

dataObject[]
List of information about the client's conduits.
Hide child attributesShow child attributes
- data.idString
  Conduit ID.
- data.shard_countInteger
  Number of shards associated with this conduit.

Response Codes

200OK: Successfully retrieved conduits.
401Unauthenticated: Authorization header required with an app access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/eventsub/conduits' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/eventsub/conduits",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/eventsub/conduits", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/eventsub/conduits");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/eventsub/conduits")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "shard_count": 15
    },
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Create Conduits

Creates a new conduit.

Endpoint

POSThttps://api.twitch.tv/helix/eventsub/conduits

Authorization

Requires one of the following:

An app access token.

Request Body

shard_countIntegerRequired
The number of shards to create for this conduit. The minimum is 1 and the maximum is 20,000.

Response Body

dataObject[]
A list that contains the conduit that you created.
Hide child attributesShow child attributes
- data.idString
  Conduit ID.
- data.shard_countInteger
  Number of shards created for this conduit.

Response Codes

200OK: Conduit created.
400Bad Request: The shard_count field is required.
The value in shard_count must be from 1 through 20,000.
401Unauthenticated: Authorization header required with an app access token.
429Too Many Requests: The client ID in the access token already has the maximum of 5 conduits.

Request Example

curl -X POST 'https://api.twitch.tv/helix/eventsub/conduits' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"shard_count":5}'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$body = '{"shard_count":5}'

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits" `
    -Method Post -Headers $headers `
    -ContentType "application/json" -Body $body

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "shard_count": 5
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.twitch.tv/helix/eventsub/conduits",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    json={
        "shard_count": 5,
    },
)

data = response.json()

body := strings.NewReader(`{"shard_count":5}`)

req, _ := http.NewRequest("POST", "https://api.twitch.tv/helix/eventsub/conduits", body)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"shard_count":5}');

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.twitch.tv/helix/eventsub/conduits");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

request.Content = new StringContent("{\"shard_count\":5}",
    Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .post("https://api.twitch.tv/helix/eventsub/conduits")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .json(&serde_json::json!({
        "shard_count": 5
    }))
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Update Conduits

Updates a conduit's shard count. To delete shards, update the count to a lower number, and the shards above the count will be deleted. For example, if the existing shard count is 100, by resetting shard count to 50, shards 50-99 are deleted.

Endpoint

PATCHhttps://api.twitch.tv/helix/eventsub/conduits

Authorization

Requires one of the following:

An app access token.

Request Body

idStringRequired
Conduit ID.
shard_countIntegerRequired
The new number of shards for this conduit. The minimum is 1 and the maximum is 20,000.

Response Body

dataObject[]
A list that contains the updated conduit.
Hide child attributesShow child attributes
- data.idString
  Conduit ID.
- data.shard_countInteger
  Number of shards associated with this conduit after the update.

Response Codes

200OK: Conduit updated.
400Bad Request: The id field is required.
The shard_count field is required.
The value in shard_count must be from 1 through 20,000.
401Unauthenticated: Authorization header required with an app access token.
404Not Found: Conduit not found.
Conduit's owner must match the client ID in the access token.

Request Example

curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"id":"bfcfc993-26b1-b876-44d9-afe75a379dac","shard_count":5}'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$body = '{"id":"bfcfc993-26b1-b876-44d9-afe75a379dac","shard_count":5}'

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits" `
    -Method Patch -Headers $headers `
    -ContentType "application/json" -Body $body

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
    "shard_count": 5
  }),
});

const data = await response.json();

import requests

response = requests.patch(
    "https://api.twitch.tv/helix/eventsub/conduits",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    json={
        "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
        "shard_count": 5,
    },
)

data = response.json()

body := strings.NewReader(`{"id":"bfcfc993-26b1-b876-44d9-afe75a379dac","shard_count":5}`)

req, _ := http.NewRequest("PATCH", "https://api.twitch.tv/helix/eventsub/conduits", body)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"id":"bfcfc993-26b1-b876-44d9-afe75a379dac","shard_count":5}');

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.twitch.tv/helix/eventsub/conduits");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

request.Content = new StringContent("{\"id\":\"bfcfc993-26b1-b876-44d9-afe75a379dac\",\"shard_count\":5}",
    Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .patch("https://api.twitch.tv/helix/eventsub/conduits")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .json(&serde_json::json!({
        "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
        "shard_count": 5
    }))
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Delete Conduit

Deletes a specified conduit. Note that it may take some time for Eventsub subscriptions on a deleted conduit to show as disabled when calling Get Eventsub Subscriptions.

Endpoint

DELETEhttps://api.twitch.tv/helix/eventsub/conduits

Authorization

Requires one of the following:

An app access token.

Query Parameters

idStringRequired
Conduit ID.

Response Codes

204No Content: Successfully deleted the conduit.
400Bad Request: The id query parameter is required.
401Unauthenticated: Authorization header required with an app access token.
404Not Found: Conduit not found.
Conduit's owner must match the client ID in the access token.

Request Example

curl -X DELETE 'https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac" `
    -Method Delete -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.delete(
    "https://api.twitch.tv/helix/eventsub/conduits",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
    },
)

data = response.json()

req, _ := http.NewRequest("DELETE", "https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Delete, "https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .delete("https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Get Conduit Shards

Gets a list of shards for a conduit. The list includes only shards that you've assigned a transport to using Update Conduit Shards, so it's empty for a new conduit.

Endpoint

GEThttps://api.twitch.tv/helix/eventsub/conduits/shards

Authorization

Requires one of the following:

An app access token.

Query Parameters

conduit_idStringRequired
Conduit ID.
statusString
Status to filter by.
Possible values
- enabled
  The shard is enabled.
- webhook_callback_verification_pending
  The shard is pending verification of the specified callback URL.
- webhook_callback_verification_failed
  The specified callback URL failed verification.
- notification_failures_exceeded
  The notification delivery failure rate was too high.
- websocket_disconnected
  The client closed the connection.
- websocket_failed_ping_pong
  The client failed to respond to a ping message.
- websocket_received_inbound_traffic
  The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
- websocket_connection_unused
  The client failed to subscribe to events within the required time.
- websocket_internal_error
  The Twitch WebSocket server experienced an unexpected error.
- websocket_network_timeout
  The Twitch WebSocket server timed out writing the message to the client.
- websocket_network_error
  The Twitch WebSocket server experienced a network error writing the message to the client.
- websocket_failed_to_reconnect
  The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
afterString
The cursor used to get the next page of results. The pagination object in the response contains the cursor's value.

Response Body

dataObject[]
List of information about a conduit's shards.
Hide child attributesShow child attributes
- data.idString
  Shard ID.
- data.statusString
  The shard status. The subscriber receives events only for enabled shards.
  Possible values
  - enabled
    The shard is enabled.
  - webhook_callback_verification_pending
    The shard is pending verification of the specified callback URL.
  - webhook_callback_verification_failed
    The specified callback URL failed verification.
  - notification_failures_exceeded
    The notification delivery failure rate was too high.
  - websocket_disconnected
    The client closed the connection.
  - websocket_failed_ping_pong
    The client failed to respond to a ping message.
  - websocket_received_inbound_traffic
    The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
  - websocket_connection_unused
    The client failed to subscribe to events within the required time.
  - websocket_internal_error
    The Twitch WebSocket server experienced an unexpected error.
  - websocket_network_timeout
    The Twitch WebSocket server timed out writing the message to the client.
  - websocket_network_error
    The Twitch WebSocket server experienced a network error writing the message to the client.
  - websocket_failed_to_reconnect
    The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
- data.transportObject
  The transport details used to send the notifications.
  Hide child attributesShow child attributes
  - data.transport.methodString
    The transport method.
    Possible values
    webhook
    websocket
  - data.transport.callbackString
    The callback URL where the notifications are sent. Included only if method is set to webhook.
  - data.transport.session_idString
    An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
  - data.transport.connected_atString
    The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
  - data.transport.disconnected_atString
    The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
paginationObject
Contains information used to page through a list of results. The object is empty if there are no more pages left to page through.
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Use the cursor to set the request's after query parameter.

Response Codes

200OK: Successfully retrieved shards.
400Bad Request: The conduit_id query parameter is required.
The cursor specified in the after query parameter is not valid.
401Unauthenticated: Authorization header required with an app access token.
404Not Found: Conduit not found.
Conduit's owner must match the client ID in the access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/eventsub/conduits/shards",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "0",
      "status": "enabled",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      }
    },
    {
      "id": "1",
      "status": "webhook_callback_verification_pending",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback-2.com"
      }
    },
    {
      "id": "2",
      "status": "enabled",
      "transport": {
        "method": "websocket",
        "session_id": "9fd5164a-a958-4c60-b7f4-6a7202506ca0",
        "connected_at": "2020-11-10T14:32:18Z"
      }
    },
    {
      "id": "3",
      "status": "enabled",
      "transport": {
        "method": "websocket",
        "session_id": "238b4b08-13f1-4b8f-8d31-56665a7a9d9f",
        "connected_at": "2020-11-10T14:32:18Z"
      }
    },
    {
      "id": "4",
      "status": "websocket_disconnected",
      "transport": {
        "method": "websocket",
        "session_id": "ad1c9fc3-0d99-4eb7-8a04-8608e8ff9ec9",
        "connected_at": "2020-11-10T14:32:18Z",
        "disconnected_at": "2020-11-11T14:32:18Z"
      }
    }
  ],
  "pagination": {}
}

Update Conduit Shards

Updates shard(s) for a conduit. You can update up to 100 shards in a single request.

Note

Shard IDs are indexed starting at 0, so a conduit with a shard_count of 5 will have shards with IDs 0 through 4.

Endpoint

PATCHhttps://api.twitch.tv/helix/eventsub/conduits/shards

Authorization

Requires one of the following:

An app access token.

Request Body

conduit_idStringRequired
Conduit ID.
shardsObject[]Required
List of shards to update.
Hide child attributesShow child attributes
- shards.idStringRequired
  Shard ID.
- shards.transportObjectRequired
  The transport details that you want Twitch to use when sending you notifications.
  Hide child attributesShow child attributes
  - shards.transport.methodStringRequired
    The transport method.
    Possible values
    webhook
    websocket
  - shards.transport.callbackString
    The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event. Specify this field only if method is set to webhook. NOTE: Redirects are not followed.
  - shards.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message. Specify this field only if method is set to webhook.
  - shards.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message. Specify this field only if method is set to websocket.

Response Body

dataObject[]
List of successful shard updates.
Hide child attributesShow child attributes
- data.idString
  Shard ID.
- data.statusString
  The shard status. The subscriber receives events only for enabled shards.
  Possible values
  - enabled
    The shard is enabled.
  - webhook_callback_verification_pending
    The shard is pending verification of the specified callback URL.
  - webhook_callback_verification_failed
    The specified callback URL failed verification.
  - notification_failures_exceeded
    The notification delivery failure rate was too high.
  - websocket_disconnected
    The client closed the connection.
  - websocket_failed_ping_pong
    The client failed to respond to a ping message.
  - websocket_received_inbound_traffic
    The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
  - websocket_internal_error
    The Twitch WebSocket server experienced an unexpected error.
  - websocket_network_timeout
    The Twitch WebSocket server timed out writing the message to the client.
  - websocket_network_error
    The Twitch WebSocket server experienced a network error writing the message to the client.
  - websocket_failed_to_reconnect
    The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
- data.transportObject
  The transport details used to send the notifications.
  Hide child attributesShow child attributes
  - data.transport.methodString
    The transport method.
    Possible values
    webhook
    websocket
  - data.transport.callbackString
    The callback URL where the notifications are sent. Included only if method is set to webhook.
  - data.transport.session_idString
    An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
  - data.transport.connected_atString
    The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
  - data.transport.disconnected_atString
    The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
errorsObject[]
List of unsuccessful updates.
Hide child attributesShow child attributes
- errors.idString
  Shard ID.
- errors.messageString
  The error that occurred while updating the shard. Possible errors:
  - invalid shard id, must be a number greater or equal to 0 and less than N — The shard ID must be a number from 0 through N - 1, where N is the conduit's shard count.
  - failed webhook transport validation: callback, must provide valid https callback with standard port in creation request — The URL in the callback field must use the HTTPS protocol and port 443.
  - failed webhook transport validation: secret, must be between 10 and 100 characters
  - failed websocket transport validation: session_id, websocket transport session does not exist or has already disconnected
  - Duplicate shards in request — The request specifies the shard ID more than once. None of the entries for that shard are applied.
  - Internal error — An internal error occurred while updating the shard. Try again later.
- errors.codeString
  Error codes used to represent a specific error condition while attempting to update shards.
  Possible values
  - invalid_parameter
    The shard ID or transport isn't valid, or the request specifies the shard ID more than once.
  - internal_error
    An internal error occurred. Try again later.

Response Codes

202Accepted: Successfully updated shards.
400Bad Request: The 'conduit_id' field is required.
The 'shards' field is required.
The 'shards' field contains more than 100 shards.
The 'shards' field contains more entries than the conduit's shard count.
The value specified in a shard's 'method' field is not valid.
The 'callback' field is required if you specify the webhook transport method.
The 'session_id' field is required if you specify the websocket transport method.
Do not specify the 'session_id' field if you specify the webhook transport method.
Do not specify the 'callback' or 'secret' fields if you specify the websocket transport method.
401Unauthenticated: Authorization header requires using an App Access Token for this request.
404Not Found: The specified 'conduit_id' does not exist.
Conduit's owner must match the Client ID in the access token.

Request Example

curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits/shards' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/eventsub/conduits/shards" `
    -Method Patch -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/eventsub/conduits/shards", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.patch(
    "https://api.twitch.tv/helix/eventsub/conduits/shards",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
)

data = response.json()

req, _ := http.NewRequest("PATCH", "https://api.twitch.tv/helix/eventsub/conduits/shards", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/eventsub/conduits/shards");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.twitch.tv/helix/eventsub/conduits/shards");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .patch("https://api.twitch.tv/helix/eventsub/conduits/shards")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "0",
      "status": "webhook_callback_verification_pending",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      }
    },
    {
      "id": "1",
      "status": "webhook_callback_verification_pending",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback-2.com"
      }
    }
  ],
  "errors": [
    {
      "id": "3",
      "message": "invalid shard id, must be a number greater or equal to 0 and less than 3",
      "code": "invalid_parameter"
    }
  ]
}