Webhooks - shortkit

The Webhooks API allows you to manage webhook endpoints that receive real-time notifications when events occur in shortkit.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/webhooks`	List webhooks
`POST`	`/v1/webhooks`	Create webhook
`GET`	`/v1/webhooks/{id}`	Get webhook details
`PATCH`	`/v1/webhooks/{id}`	Update webhook
`DELETE`	`/v1/webhooks/{id}`	Delete webhook
`POST`	`/v1/webhooks/{id}/rotate-secret`	Rotate signing secret
`POST`	`/v1/webhooks/{id}/test`	Send test event
`GET`	`/v1/webhooks/{id}/deliveries`	List delivery attempts

List webhooks

Retrieve all configured webhooks.

GET /v1/webhooks

Example request

curl https://api.shortkit.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": [
    {
      "id": "whk_abc123",
      "url": "https://yourserver.com/webhooks/shortkit",
      "events": ["content.ready", "content.errored"],
      "description": "Production webhook",
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

Create webhook

POST /v1/webhooks

Request body

url

string

required

HTTPS endpoint URL to receive events.

events

string[]

required

Events to subscribe to.

description

string

Optional description.

Available events

Event	Description
`content.ready`	Content finished processing
`content.errored`	Content processing failed
`export.ready`	Data export completed

Example request

curl -X POST https://api.shortkit.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/shortkit",
    "events": ["content.ready", "content.errored"],
    "description": "Production webhook"
  }'

Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://yourserver.com/webhooks/shortkit",
    "events": ["content.ready", "content.errored"],
    "description": "Production webhook",
    "secret": "whsec_xyz789abc...",
    "status": "active",
    "createdAt": "2024-02-04T12:00:00Z"
  }
}

The signing secret is only returned once when creating the webhook. Store it securely.

Get webhook

Retrieve webhook details.

GET /v1/webhooks/{id}

Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://yourserver.com/webhooks/shortkit",
    "events": ["content.ready", "content.errored"],
    "description": "Production webhook",
    "status": "active",
    "stats": {
      "totalDeliveries": 1250,
      "successfulDeliveries": 1245,
      "failedDeliveries": 5,
      "lastDeliveryAt": "2024-02-04T11:55:00Z"
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Update webhook

Modify webhook configuration.

PATCH /v1/webhooks/{id}

Request body

url

string

Updated endpoint URL.

events

string[]

Updated event subscriptions.

description

string

Updated description.

status

string

Status: active or disabled.

Example request

curl -X PATCH https://api.shortkit.dev/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["content.ready", "content.errored", "export.ready"]
  }'

Disable webhook

curl -X PATCH https://api.shortkit.dev/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "disabled"
  }'

Delete webhook

Remove a webhook endpoint.

DELETE /v1/webhooks/{id}

Example request

curl -X DELETE https://api.shortkit.dev/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "id": "whk_abc123",
    "deleted": true
  }
}

Rotate secret

Generate a new signing secret for a webhook.

POST /v1/webhooks/{id}/rotate-secret

Example request

curl -X POST https://api.shortkit.dev/v1/webhooks/whk_abc123/rotate-secret \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "id": "whk_abc123",
    "secret": "whsec_newSecret123...",
    "previousSecretExpiresAt": "2024-02-04T13:00:00Z"
  }
}

The previous secret remains valid for 1 hour after rotation, allowing time to update your endpoint.

Send test event

Send a test event to verify endpoint configuration.

POST /v1/webhooks/{id}/test

Request body

event

string

required

Event type to send.

Example request

curl -X POST https://api.shortkit.dev/v1/webhooks/whk_abc123/test \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "content.ready"
  }'

Response

{
  "data": {
    "deliveryId": "del_test123",
    "status": "success",
    "statusCode": 200,
    "responseTime": 245,
    "response": "OK"
  }
}

List deliveries

View webhook delivery history.

GET /v1/webhooks/{id}/deliveries

Query parameters

limit

integer

default:20

Items per page.

status

string

Filter by status: success, failed, pending.

Example request

curl "https://api.shortkit.dev/v1/webhooks/whk_abc123/deliveries?limit=10" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": [
    {
      "id": "del_xyz789",
      "event": "content.ready",
      "status": "success",
      "statusCode": 200,
      "attempts": 1,
      "responseTime": 185,
      "payload": {
        "event": "content.ready",
        "data": {
          "contentId": "cnt_abc123",
          "title": "My Video"
        }
      },
      "createdAt": "2024-02-04T11:55:00Z"
    },
    {
      "id": "del_abc456",
      "event": "content.errored",
      "status": "failed",
      "attempts": 6,
      "lastAttemptAt": "2024-02-04T10:30:00Z",
      "lastError": "Connection timeout",
      "createdAt": "2024-02-04T10:00:00Z"
    }
  ],
  "meta": {
    "total": 150
  }
}

Retry delivery

Retry a failed delivery.

POST /v1/webhooks/{webhookId}/deliveries/{deliveryId}/retry

Example request

curl -X POST https://api.shortkit.dev/v1/webhooks/whk_abc123/deliveries/del_abc456/retry \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "id": "del_abc456",
    "status": "pending",
    "attempts": 7,
    "nextAttemptAt": "2024-02-04T12:00:00Z"
  }
}

Webhook payload format

All webhook events have a consistent format:

{
  "event": "content.ready",
  "data": {
    "contentId": "cnt_abc123",
    "title": "My Video",
    "duration": 45.2,
    "status": "ready"
  },
  "timestamp": "2024-02-04T12:00:00Z",
  "webhookId": "whk_abc123"
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-Shortform-Signature`	HMAC-SHA256 signature
`X-Shortform-Timestamp`	Event timestamp
`X-Shortform-Webhook-ID`	Webhook configuration ID
`X-Shortform-Delivery-ID`	Unique delivery attempt ID

Retry policy

Failed deliveries are automatically retried:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	24 hours

After all retries are exhausted, the delivery is marked as failed.

SDK examples

JavaScript
Python

import { ShortkitAdmin } from '@shortkit/node';

const shortkit = new ShortkitAdmin({ apiKey: 'sk_live_...' });

// Create webhook
const webhook = await shortkit.webhooks.create({
  url: 'https://yourserver.com/webhooks/shortkit',
  events: ['content.ready', 'content.errored']
});

console.log('Signing secret:', webhook.secret);

// List webhooks
const webhooks = await shortkit.webhooks.list();

// Send test event
await shortkit.webhooks.test(webhook.id, { event: 'content.ready' });

from shortkit import ShortkitAdmin

shortkit = ShortkitAdmin(api_key='sk_live_...')

# Create webhook
webhook = shortkit.webhooks.create(
    url='https://yourserver.com/webhooks/shortkit',
    events=['content.ready', 'content.errored']
)

print(f'Signing secret: {webhook.secret}')

# List webhooks
webhooks = shortkit.webhooks.list()

# Send test event
shortkit.webhooks.test(webhook.id, event='content.ready')

Overview

Content

Feed

Analytics

Configuration

​Endpoints

​List webhooks

​Example request

​Response

​Create webhook

​Request body

​Available events

​Example request

​Response

​Get webhook

​Response

​Update webhook

​Request body

​Example request

​Disable webhook

​Delete webhook

​Example request

​Response

​Rotate secret

​Example request

​Response

​Send test event

​Request body

​Example request

​Response

​List deliveries

​Query parameters

​Example request

​Response

​Retry delivery

​Example request

​Response

​Webhook payload format

​Headers

​Retry policy

​SDK examples

​Next steps

Webhooks guide

Content API

Endpoints

List webhooks

Example request

Response

Create webhook

Request body

Available events

Example request

Response

Get webhook

Response

Update webhook

Request body

Example request

Disable webhook

Delete webhook

Example request

Response

Rotate secret

Example request

Response

Send test event

Request body

Example request

Response

List deliveries

Query parameters

Example request

Response

Retry delivery

Example request

Response

Webhook payload format

Headers

Retry policy

SDK examples

Next steps