Create Webhook

curl --request POST \
  --url https://api.example.com/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "event_types": [
    "<string>"
  ],
  "is_active": false,
  "receive_simulated_events": false,
  "purchase_date_start": "2023-12-25",
  "purchase_date_end": "2023-12-25"
}
'

import requests

url = "https://api.example.com/webhooks"

payload = {
    "name": "<string>",
    "url": "<string>",
    "event_types": ["<string>"],
    "is_active": False,
    "receive_simulated_events": False,
    "purchase_date_start": "2023-12-25",
    "purchase_date_end": "2023-12-25"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    url: '<string>',
    event_types: ['<string>'],
    is_active: false,
    receive_simulated_events: false,
    purchase_date_start: '2023-12-25',
    purchase_date_end: '2023-12-25'
  })
};

fetch('https://api.example.com/webhooks', 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.example.com/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'url' => '<string>',
    'event_types' => [
        '<string>'
    ],
    'is_active' => false,
    'receive_simulated_events' => false,
    'purchase_date_start' => '2023-12-25',
    'purchase_date_end' => '2023-12-25'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}")

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

	req.Header.Add("Content-Type", "application/json")

	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.example.com/webhooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webhooks")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}"

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

{
  "webhook_id": "<string>",
  "name": "<string>",
  "url": "<string>",
  "is_active": true,
  "event_types": [
    "<string>"
  ],
  "receive_simulated_events": true,
  "purchase_date_start": "2023-12-25",
  "purchase_date_end": "2023-12-25",
  "created_at": "2023-11-07T05:31:56Z",
  "signing_secret": "<string>"
}

POST

webhooks

Create Webhook

curl --request POST \
  --url https://api.example.com/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "event_types": [
    "<string>"
  ],
  "is_active": false,
  "receive_simulated_events": false,
  "purchase_date_start": "2023-12-25",
  "purchase_date_end": "2023-12-25"
}
'

import requests

url = "https://api.example.com/webhooks"

payload = {
    "name": "<string>",
    "url": "<string>",
    "event_types": ["<string>"],
    "is_active": False,
    "receive_simulated_events": False,
    "purchase_date_start": "2023-12-25",
    "purchase_date_end": "2023-12-25"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    url: '<string>',
    event_types: ['<string>'],
    is_active: false,
    receive_simulated_events: false,
    purchase_date_start: '2023-12-25',
    purchase_date_end: '2023-12-25'
  })
};

fetch('https://api.example.com/webhooks', 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.example.com/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'url' => '<string>',
    'event_types' => [
        '<string>'
    ],
    'is_active' => false,
    'receive_simulated_events' => false,
    'purchase_date_start' => '2023-12-25',
    'purchase_date_end' => '2023-12-25'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}")

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

	req.Header.Add("Content-Type", "application/json")

	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.example.com/webhooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webhooks")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"url\": \"<string>\",\n  \"event_types\": [\n    \"<string>\"\n  ],\n  \"is_active\": false,\n  \"receive_simulated_events\": false,\n  \"purchase_date_start\": \"2023-12-25\",\n  \"purchase_date_end\": \"2023-12-25\"\n}"

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

{
  "webhook_id": "<string>",
  "name": "<string>",
  "url": "<string>",
  "is_active": true,
  "event_types": [
    "<string>"
  ],
  "receive_simulated_events": true,
  "purchase_date_start": "2023-12-25",
  "purchase_date_end": "2023-12-25",
  "created_at": "2023-11-07T05:31:56Z",
  "signing_secret": "<string>"
}

Subtotal Connector tool: create_webhook

Access

Call this endpoint with your API key, or with a Subtotal Connector OAuth token that includes webhooks:write. A token without webhooks:write receives 403 insufficient_scope. Partner app tokens don’t include it.

Example

curl --request POST 'https://api.subtotal.com/webhooks' \
  --header "x-api-key: $SUBTOTAL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Order sync",
    "url": "https://hooks.example.com/subtotal",
    "event_types": ["connection.activated", "purchase.created"],
    "is_active": true
  }'

{
  "webhook_id": "01JA7Q2W3E4R5T6Y7U8I9O0P1A",
  "name": "Order sync",
  "url": "https://hooks.example.com/subtotal",
  "is_active": true,
  "event_types": ["connection.activated", "purchase.created"],
  "receive_simulated_events": false,
  "purchase_date_start": null,
  "purchase_date_end": null,
  "created_at": "2026-10-14T17:02:11Z",
  "signing_secret": "Vq3n…"
}

A new webhook starts paused unless the request sets is_active to true, as in this example. Use event_types names from Event types; an unknown name returns a 422 that lists the valid names.

signing_secret is returned only in this response and can’t be read back. Store it now and use it to verify webhook signatures. If you lose it, delete the webhook and create a new one.

URL requirements

https, on port 443, with no username or password in the URL.
The host must resolve, and only to public IP addresses. A host that resolves to a private, loopback, link-local or other non-public address is rejected.

Errors

Status	When
`422`	A URL that doesn’t meet the requirements above, an unknown event type, no event types, a name already used by another of your webhooks, or `purchase_date_start` after `purchase_date_end`

Headers

authorization

string | null

x-api-key

string | null

Body

application/json

name

string

required

Unique per account.

Required string length: 1 - 64

url

string

required

HTTPS URL on port 443 that receives the events.

Maximum string length: 256

event_types

string[]

required

Event names to subscribe to, e.g. purchase.created.

Minimum array length: 1

is_active

boolean

default:false

Start delivering immediately. By default the webhook is created paused.

receive_simulated_events

boolean

default:false

purchase_date_start

string<date> | null

purchase_date_end

string<date> | null

Response

Successful Response

webhook_id

string

required

name

string

required

url

string

required

is_active

boolean

required

event_types

string[]

required

Subscribed event names, e.g. purchase.created.

receive_simulated_events

boolean

required

Also deliver events from the simulator.

purchase_date_start

string<date> | null

required

Only purchases on or after this date; null = unbounded.

purchase_date_end

string<date> | null

required

Only purchases on or before this date; null = unbounded.

created_at

string<date-time>

required

signing_secret

string

required

Verifies the X-Subtotal-Signature header. Shown only in this response; store it now.

API Reference

Connections

Link Tokens

Connection Tokens

Purchases

Products

Product groups

Retailers

Event simulator

Webhooks

Create Webhook

Access

Example

URL requirements

Errors

Headers

Body

Response

​Access

​Example

​URL requirements

​Errors

Headers

Body

Response

Access

Example

URL requirements

Errors