Create a webhook endpoint - Spree Commerce documentation

POST

api

admin

webhook_endpoints

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const endpoint = await client.webhookEndpoints.create({
  name: 'Order pipeline',
  url: 'https://example.com/webhooks/orders',
  active: true,
  subscriptions: ['order.completed', 'order.canceled'],
})

// The plaintext `secret_key` is returned exactly once on create — persist it
// immediately so you can verify incoming webhook signatures. Subsequent reads
// will return `null`.
const signingSecret = endpoint.secret_key

spree api post /webhook_endpoints -d '{"name":"Order pipeline","url":"https://example.com/webhooks/orders","active":true,"subscriptions":["order.completed","order.canceled"]}'

{
  "id": "whe_gbHJdmfrXB",
  "name": "CI integration",
  "url": "https://ci.example.com/webhooks",
  "active": true,
  "subscriptions": [
    "order.completed"
  ],
  "disabled_reason": null,
  "created_at": "2026-07-27T20:01:50.936Z",
  "updated_at": "2026-07-27T20:01:50.936Z",
  "disabled_at": null,
  "secret_key": "90ad965cc1c4d99ff9b7d7cf3b8f926a4658097c48c0271d492a5b059fd1620b",
  "last_delivery_at": null,
  "recent_delivery_count": 0,
  "recent_failure_count": 0,
  "total_delivery_count": 0,
  "successful_delivery_count": 0,
  "failed_delivery_count": 0
}

{
  "error": {
    "code": "validation_error",
    "message": "Url Translation missing. Options considered were:\n- en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url\n- en.activerecord.errors.models.spree/webhook_endpoint.invalid_url\n- en.activerecord.errors.messages.invalid_url\n- en.errors.attributes.url.invalid_url\n- en.errors.messages.invalid_url",
    "details": {
      "url": [
        "Translation missing. Options considered were:\n- en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url\n- en.activerecord.errors.models.spree/webhook_endpoint.invalid_url\n- en.activerecord.errors.messages.invalid_url\n- en.errors.attributes.url.invalid_url\n- en.errors.messages.invalid_url"
      ]
    }
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Body

application/json

url

string

required

Example:

"https://example.com/webhooks/orders"

name

string

Example:

"Order pipeline"

active

boolean

Example:

true

subscriptions

string[]

Example:

["order.completed", "order.canceled"]

Response

webhook endpoint created — secret_key returned once

List webhook endpoints

Get a webhook endpoint

⌘I

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const endpoint = await client.webhookEndpoints.create({
  name: 'Order pipeline',
  url: 'https://example.com/webhooks/orders',
  active: true,
  subscriptions: ['order.completed', 'order.canceled'],
})

// The plaintext `secret_key` is returned exactly once on create — persist it
// immediately so you can verify incoming webhook signatures. Subsequent reads
// will return `null`.
const signingSecret = endpoint.secret_key

spree api post /webhook_endpoints -d '{"name":"Order pipeline","url":"https://example.com/webhooks/orders","active":true,"subscriptions":["order.completed","order.canceled"]}'

{
  "id": "whe_gbHJdmfrXB",
  "name": "CI integration",
  "url": "https://ci.example.com/webhooks",
  "active": true,
  "subscriptions": [
    "order.completed"
  ],
  "disabled_reason": null,
  "created_at": "2026-07-27T20:01:50.936Z",
  "updated_at": "2026-07-27T20:01:50.936Z",
  "disabled_at": null,
  "secret_key": "90ad965cc1c4d99ff9b7d7cf3b8f926a4658097c48c0271d492a5b059fd1620b",
  "last_delivery_at": null,
  "recent_delivery_count": 0,
  "recent_failure_count": 0,
  "total_delivery_count": 0,
  "successful_delivery_count": 0,
  "failed_delivery_count": 0
}

{
  "error": {
    "code": "validation_error",
    "message": "Url Translation missing. Options considered were:\n- en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url\n- en.activerecord.errors.models.spree/webhook_endpoint.invalid_url\n- en.activerecord.errors.messages.invalid_url\n- en.errors.attributes.url.invalid_url\n- en.errors.messages.invalid_url",
    "details": {
      "url": [
        "Translation missing. Options considered were:\n- en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url\n- en.activerecord.errors.models.spree/webhook_endpoint.invalid_url\n- en.activerecord.errors.messages.invalid_url\n- en.errors.attributes.url.invalid_url\n- en.errors.messages.invalid_url"
      ]
    }
  }
}