Webhook Endpoints

Rotate a webhook endpoint's signing secret

Generates a new signing secret and returns it once — store it securely. The previous secret stays valid for a grace window (deliveries are co-signed with both secrets, each as its own v1= segment in X-Conduit-Signature) so you can roll over your verification code without dropping events. After the grace window only the new secret signs. Requires an Idempotency-Key: a retried request with the same key replays the original response instead of rotating again, so a lost response can’t silently discard the secret you just deployed.

POST

webhooks

endpoints

{id}

rotate

Rotate a webhook endpoint's signing secret

curl --request POST \
  --url https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'x-api-key': '<api-key>'}
};

fetch('https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate"

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'

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

{
  "id": "<string>",
  "url": "https://api.example.com/webhooks/conduit",
  "description": "Production webhook receiver",
  "status": "active",
  "subscription": {
    "mode": "all"
  },
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "secret": "whsec_8f3a2b1c4d5e6f7081928374a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e",
  "signature": {
    "algorithm": "hmac-sha256",
    "headerName": "X-Conduit-Signature",
    "headerFormat": "t=<unix-seconds>,v1=<hex-digest>[,v1=<hex-digest>]",
    "signedPayloadFormat": "<unix-seconds>.<raw-request-body>",
    "secretFormat": "whsec_<64-hex>"
  }
}

{
  "type": "INVALID_OID_FORMAT",
  "title": "Invalid Object ID Format",
  "status": 400,
  "detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
  "resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
  "docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_MISSING",
  "title": "API Key Missing",
  "status": 401,
  "detail": "The request did not include an API key. All API requests must be authenticated.",
  "resolution": "Include your API key in the 'x-api-key' header with every request.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_READ_ONLY",
  "title": "API Key Is Read-Only",
  "status": 403,
  "detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
  "resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "WEBHOOK_ENDPOINT_NOT_FOUND",
  "title": "Webhook Endpoint Not Found",
  "status": 404,
  "detail": "No webhook endpoint exists with the specified ID, or it belongs to a different organization.",
  "resolution": "Verify the endpoint ID is correct. Use the list webhook endpoints endpoint to find valid IDs for your organization.",
  "docs": "https://conduit-v2.mintlify.app/errors#webhook-endpoint-not-found",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
  "resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
  "docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "UNSUPPORTED_MEDIA_TYPE",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
  "resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
  "docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "RATE_LIMITED",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
  "resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
  "docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z",
  "retryAfterSeconds": 3
}

{
  "type": "INTERNAL_ERROR",
  "title": "Internal Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
  "docs": "https://conduit-v2.mintlify.app/errors#internal-error",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Authorizations

x-api-key

string

header

required

Headers

Idempotency-Key

string

required

Caller-generated unique key that lets the server safely replay this request. The original response is returned for 30 days on any retry with the same key from the same organization. Required on every state-changing money-moving or resource-creating POST.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9_.:-]{1,128}$

Example:

"01J7B3K2X9M8N5P6Q7R8S9T0V1"

Path Parameters

string

required

Example:

"wep_1A2b3C4d5E6f7G8h9I0jKl"

Response

string

required

Unique webhook endpoint identifier

Pattern: ^wep_[0-9A-Za-z]{22}$

url

string

required

URL where webhook payloads are delivered

Example:

"https://api.example.com/webhooks/conduit"

description

string | null

required

Human-readable description of this endpoint's purpose

Example:

"Production webhook receiver"

status

enum<string>

required

Whether this endpoint is currently receiving new deliveries. When disabled, the endpoint is excluded from event fan-out — no new deliveries are enqueued. In-flight (already-enqueued) deliveries are not cancelled and continue retrying per the normal schedule. Set back to active via PATCH to resume receiving new deliveries.

Available options:

active,

disabled

subscription

object

required

Event subscription configuration for this endpoint

Option 1
Option 2

Show child attributes

createdAt

string<date-time>

required

ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

updatedAt

string<date-time>

required

ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

secret

string

required

Per-endpoint signing secret. Returned only once — when the endpoint is created and again each time its secret is rotated — so store it securely. Format: literal whsec_ prefix + 64 hex chars (see signature.secretFormat). Pass the FULL string verbatim, including the whsec_ prefix, as the HMAC-SHA256 key when verifying incoming X-Conduit-Signature headers — stripping the prefix produces a different digest and every valid delivery fails verification.

Example:

"whsec_8f3a2b1c4d5e6f7081928374a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e"

signature

object

required

Signature verification metadata. Same constants apply to every webhook delivery; signing secrets are per-endpoint.

Show child attributes

⌘I

Rotate a webhook endpoint's signing secret

curl --request POST \
  --url https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'x-api-key': '<api-key>'}
};

fetch('https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate"

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.conduit.financial/v2/webhooks/endpoints/{id}/rotate")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'

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

{
  "id": "<string>",
  "url": "https://api.example.com/webhooks/conduit",
  "description": "Production webhook receiver",
  "status": "active",
  "subscription": {
    "mode": "all"
  },
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "secret": "whsec_8f3a2b1c4d5e6f7081928374a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e",
  "signature": {
    "algorithm": "hmac-sha256",
    "headerName": "X-Conduit-Signature",
    "headerFormat": "t=<unix-seconds>,v1=<hex-digest>[,v1=<hex-digest>]",
    "signedPayloadFormat": "<unix-seconds>.<raw-request-body>",
    "secretFormat": "whsec_<64-hex>"
  }
}

{
  "type": "INVALID_OID_FORMAT",
  "title": "Invalid Object ID Format",
  "status": 400,
  "detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
  "resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
  "docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_MISSING",
  "title": "API Key Missing",
  "status": 401,
  "detail": "The request did not include an API key. All API requests must be authenticated.",
  "resolution": "Include your API key in the 'x-api-key' header with every request.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_READ_ONLY",
  "title": "API Key Is Read-Only",
  "status": 403,
  "detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
  "resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
  "docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "WEBHOOK_ENDPOINT_NOT_FOUND",
  "title": "Webhook Endpoint Not Found",
  "status": 404,
  "detail": "No webhook endpoint exists with the specified ID, or it belongs to a different organization.",
  "resolution": "Verify the endpoint ID is correct. Use the list webhook endpoints endpoint to find valid IDs for your organization.",
  "docs": "https://conduit-v2.mintlify.app/errors#webhook-endpoint-not-found",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
  "resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
  "docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "UNSUPPORTED_MEDIA_TYPE",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
  "resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
  "docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "RATE_LIMITED",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
  "resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
  "docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z",
  "retryAfterSeconds": 3
}

{
  "type": "INTERNAL_ERROR",
  "title": "Internal Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
  "docs": "https://conduit-v2.mintlify.app/errors#internal-error",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Overview

Errors

Customers

Registered Addresses

Wallets

Wallet Signers

Signing Quorum

Virtual Accounts

Applications

Documents

Verifications

Signing Requests

Transactions

Payouts

RFIs

Whitelist Recipients

Orders

Quotes

Webhook Endpoints

Webhook Deliveries

Webhook Event Types

Features

Customer Onboarding

Markup

Sandbox

Rotate a webhook endpoint's signing secret

Authorizations

Headers

Path Parameters

Response