Webhook Subscriptions

Add a new signing secret (rotation)

POST

/webhook_subscriptions/{id}/secrets

package main

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

func main() {

  url := "https://api.kirimdev.com/v1/webhook_subscriptions/wbs_01HXYZABCDEFGHJKMNPQRSTVWX/secrets"

  payload := strings.NewReader("{ \"expires_in_hours\": 1 }")

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

  req.Header.Add("Idempotency-Key", "order-20260910-0001")
  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))

}

const url = 'https://api.kirimdev.com/v1/webhook_subscriptions/wbs_01HXYZABCDEFGHJKMNPQRSTVWX/secrets';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'order-20260910-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"expires_in_hours":1}'
};

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

use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.kirimdev.com/v1/webhook_subscriptions/wbs_01HXYZABCDEFGHJKMNPQRSTVWX/secrets";

    let payload = json!({"expires_in_hours": 1});

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Idempotency-Key", "order-20260910-0001".parse().unwrap());
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request POST \
  --url https://api.kirimdev.com/v1/webhook_subscriptions/wbs_01HXYZABCDEFGHJKMNPQRSTVWX/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-20260910-0001' \
  --data '{ "expires_in_hours": 1 }'

Issue a new signing secret with the given expiry. The plaintext secret is returned in the initial response and replayed for 24 hours when the same POST is retried with the same Idempotency-Key. During the overlap window every active secret is used to sign outbound deliveries; subscribers verify against any of them.

Authorizations

bearerAuth

Parameters

Path Parameters

required

Public Kirimdev webhook-subscription ID.

string

/^wbs_[0-9A-HJKMNP-TV-Z]{26}$/

Example

wbs_01HXYZABCDEFGHJKMNPQRSTVWX

Public Kirimdev webhook-subscription ID.

Header Parameters

Idempotency-Key

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

string

Example

order-20260910-0001

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

Request Body

application/json

object

expires_in_hours

integer

>= 1 <= 336

Example ^generated

{
  "expires_in_hours": 1
}

Responses

200

New secret created

application/json

object

data

required

The requested resource.

object

required

string

object

required

string

Allowed values: webhook_secret

secret

required

string

created_at

required

string format: date-time

expires_at

required

string | null format: date-time

request_id

required

Unique request identifier to include when contacting support.

string

Example

{
  "data": {
    "object": "webhook_secret"
  },
  "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

400

Validation failure

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

A field value is invalid.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field_value",
    "message": "A field value is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

401

Authentication failure

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

The provided API key is invalid.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

404

Resource not found

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Resource not found.

{
  "error": {
    "type": "not_found",
    "code": "resource_not_found",
    "message": "Resource not found.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

409

Conflict (e.g. template already exists, webhook subscription disabled, setup link inactive)

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

An identical request is still being processed. Retry later.

{
  "error": {
    "type": "conflict",
    "code": "idempotency_in_progress",
    "message": "An identical request is still being processed. Retry later.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

422

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Idempotency-Key was reused with a different request body.

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_reuse",
    "message": "Idempotency-Key was reused with a different request body.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

429

Rate limit exceeded

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Rate limit exceeded.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

500

Internal server error

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

An unexpected error occurred.

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

503

Service unavailable

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Service temporarily unavailable.

{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

Add a new signing secret (rotation)

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Request Body

Example generated

Responses

200

Example

400

Examples

401

Examples

404

Examples

409

Examples

422

Examples

429

Examples

500

Examples

503

Examples

Example ^generated