Biklo for developersTESTsandbox-api.biklo.comchange

Edit an endpoint

PUT/v1/webhooks/{id}

scope webhooks.manage

Change what an endpoint subscribes to, or replace its custom headers, WITHOUT reissuing its signing secret. Rotating a gateway credential should not force a redeploy of your signature verification — deleting and re-registering would, because a new endpoint gets a new secret. Send events, headers, or both; anything you leave out is untouched. Sending neither is nothing_to_update (400).

Request body#

FieldTypeRequiredDescription
eventsarrayoptionalReplaces the subscription. An empty array means every event, including ones added later. An unrecognised name is unknown_event (400).
headersarray|objectoptionalREPLACES the whole set — we cannot show you what is stored, so there is nothing sensible to merge into. Send every header you want kept, or an empty list to remove them all. Same two shapes as registration: [{name, value}] or {"Name": "value"}. At most 5, valid token names, 500-character values, and no reserved names (invalid_header, 400).
headers[].namestringoptionalThe header name, e.g. X-Api-Key. A valid HTTP token: letters, digits and -.
headers[].valuestringoptionalWhat to send. Stored encrypted, never returned, and never written to a delivery record.

Example

{
    "headers": [
        {
            "name": "X-Api-Key",
            "value": "the rotated value"
        }
    ]
}

Response#

FieldTypeDescription
idintegerThe endpoint you edited. Unchanged.
urlstringWhere we POST events. Not editable — a different URL is a different endpoint.
eventsstring[]|stringWhat it is subscribed to now, or the string all.
is_activebooleanWhether we are still delivering to it. Editing does not switch a disabled endpoint back on — use POST /v1/webhooks/{id}/enable.
consecutive_failuresintegerFailures in a row. Editing does not reset it.
disabled_atstring|nullISO-8601 UTC of when it was switched off, or null while active.
headersarrayThe custom headers now in force, as {name, preview}.
headers[].namestringThe header name we send.
headers[].previewstringThe first four characters of the value, then dots. Enough to tell two credentials apart, useless to anyone who does not already have it.
secret_prefixstringThe first characters of the signing secret. UNCHANGED by this call — that is the point of it.
created_atstringISO-8601 UTC of when the endpoint was registered.

Example

{
    "id": 1,
    "url": "https://erp.example.com/hooks/biklo",
    "events": [
        "order.created"
    ],
    "is_active": true,
    "consecutive_failures": 0,
    "disabled_at": null,
    "headers": [
        {
            "name": "X-Api-Key",
            "preview": "the ••••••••"
        }
    ],
    "secret_prefix": "whsec_64Ky4…",
    "created_at": "2026-09-21T09:14:03Z"
}

Failures use the shared error envelope — a machine-readable code and a request_id to quote to support. Error handling.

curl -X PUT "https://sandbox-api.biklo.com/v1/webhooks/711" \
  -H "Authorization: Bearer bk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": [
        {
            "name": "X-Api-Key",
            "value": "the rotated value"
        }
    ]
}'
<?php

$ch = curl_init('https://sandbox-api.biklo.com/v1/webhooks/711');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer bk_test_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
      'headers' => [
        0 => [
          'name' => 'X-Api-Key',
          'value' => 'the rotated value',
        ],
      ],
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "bk_test_YOUR_KEY");

var request = new HttpRequestMessage(
    new HttpMethod("PUT"),
    "https://sandbox-api.biklo.com/v1/webhooks/711");

request.Content = new StringContent(
    @"{ ""headers"": [ { ""name"": ""X-Api-Key"", ""value"": ""the rotated value"" } ] }",
    System.Text.Encoding.UTF8,
    "application/json");

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

import requests

response = requests.put(
    "https://sandbox-api.biklo.com/v1/webhooks/711",
    headers={"Authorization": "Bearer bk_test_YOUR_KEY"},
    json={
        "headers": [
            {
                "name": "X-Api-Key",
                "value": "the rotated value"
            }
        ]
    },
)

data = response.json()

const response = await fetch("https://sandbox-api.biklo.com/v1/webhooks/711", {
  method: "PUT",
  headers: {
    Authorization: "Bearer bk_test_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "headers": [
          {
              "name": "X-Api-Key",
              "value": "the rotated value"
          }
      ]
  })
});

const data = await response.json();

import java.net.http.*;
import java.net.URI;

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox-api.biklo.com/v1/webhooks/711"))
    .header("Authorization", "Bearer bk_test_YOUR_KEY")
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString(
        "{ \"headers\": [ { \"name\": \"X-Api-Key\", \"value\": \"the rotated value\" } ] }"))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());