---
title: "Create a webhook endpoint"
description: "Subscribes a URL to events."
canonical: "https://docs.printags.com/create-a-webhook-endpoint/"
last_updated: "2026-11-16"
---

# Create a webhook endpoint

`POST /v2/accounts/{accountId}/webhooks`

Subscribes a URL to events. The answer holds the signing `secret`, given this once only: store it. The URL must be public (http or https, 255 characters at most); at most 25 endpoints per account. An endpoint created with an OAuth token is removed when that authorization is revoked. Events, delivered as a JSON `POST` to the endpoint: `order.created` (an order is created, a firm order once processed), `order.updated` (every status change of an order: `data.status` is the new status, e.g. `in_queue`, `manufacturing`, `shipped`, `delivered`, `cancelled`) and `order.shipped` (the order left: `data.shippings[].trackingNumber` carries the tracking number; sent again when a new label gives a new number). `order.encoded` is accepted in `events` but not sent today. The body: `{ id, created, event, livemode, data }`, `id` the event's id (the same for every endpoint and every retry: deduplicate on it), `created` its epoch seconds, `data` the order as `getOrder` returns it in version 1. Headers: `X-Printags-Event` (the event), `X-Printags-Delivery` (the delivery's id) and `X-Printags-Signature: t=<epoch seconds>,v1=<hex>`, where `v1` is the HMAC-SHA256, keyed by the endpoint's `secret` (`whsec_...`), of `<t>.<raw body>`: recompute it on the raw bytes, compare in constant time and refuse a `t` more than 5 minutes old. Answer 2xx within 10 seconds; anything else is retried with a backoff, up to 15 attempts. An endpoint created with a test credential (a `sk_test_` key, a test OAuth token) receives test orders' events only (`livemode` false); any other endpoint receives the events of both, told apart by `livemode`.

## Authentication

An API key as a Bearer token: `Authorization: Bearer <key>`. A `sk_test_` key creates and sees test orders only. Keys and test mode: [overview](/).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string | yes | Unique identifier of the account, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. |

## Request body

Content type: `application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | yes |  |
| `events` | array of string | yes |  |
| `description` | string, nullable | no |  |

```json
{
  "url": "https://boutique.example/wp-json/printags/v1/webhook",
  "events": [
    "order.updated",
    "order.shipped"
  ],
  "description": "WooCommerce"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | The endpoint, and its signing secret |
| 400 | `url` or `events` missing (`MISSING_PARAMETERS`), a URL that is not public (`INVALID_WEBHOOK_URL`), a bad list (`INVALID_PARAMETERS`), or an event name that does not exist (`UNKNOWN_WEBHOOK_EVENTS`, with `unknown_events`) |
| 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) |
| 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); with an OAuth access token: a token of scope `mcp` (`INSUFFICIENT_SCOPE`), a path naming another account or a person no longer a member of it (`ACCOUNT_ACCESS_DENIED`), a real token on the sandbox host (`SANDBOX_REQUIRES_TEST_KEY`) |
| 409 | The account already holds 25 endpoints (`WEBHOOK_LIMIT_REACHED`) |
| 500 | Internal server error |

### 200 response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | no |  |
| `secret` | string | no | The HMAC key of `X-Printags-Signature`, given only here |
| `webhook` | [Webhook](/schemas/webhook/) | no |  |

```json
{
  "success": true,
  "secret": "whsec_0f3c...",
  "webhook": {
    "id": "3c0e8f8a-0000-4000-8000-000000000001",
    "endpoint": "https://boutique.example/wp-json/printags/v1/webhook",
    "description": "WooCommerce",
    "webhook_events": [
      {
        "name": "order.shipped"
      }
    ]
  }
}
```

## Example

```bash
curl -X POST "https://api.printags.com/v2/accounts/@me/webhooks" \
  -H "Authorization: Bearer $PRINTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://boutique.example/wp-json/printags/v1/webhook","events":["order.updated","order.shipped"],"description":"WooCommerce"}'
```
