Register a webhook endpoint (v2)

POST /api/v2/webhooks Requires authentication v2

Send a bearer token in the Authorization header.

We POST a signed JSON payload to your URL for each subscribed event. Verify the X-Acme-Signature header before trusting a delivery.

Full URL: https://api.acme.example/api/v2/webhooks

Body parameters

Name	Type	Required	Description
url	string<uri>	yes	Must be HTTPS.
events	array	yes	At least one event.

Responses

201 The registered endpoint, including the signing secret.

422 Validation failed.

Example request

cURL

curl -X POST 'https://api.acme.example/api/v2/webhooks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "events": [
        "order.paid"
    ]
}'

JavaScript

const response = await fetch('https://api.acme.example/api/v2/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "url": "https://example.com",
      "events": [
          "order.paid"
      ]
  })
});

const data = await response.json();

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_TOKEN',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
])->post('https://api.acme.example/api/v2/webhooks', [
    'url' => 'https://example.com',
    'events' => [
        'order.paid',
    ],
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://api.acme.example/api/v2/webhooks', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'url' => 'https://example.com',
        'events' => [
            'order.paid',
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true);

Example response

201

{
    "id": "whk_3f9",
    "url": "https://example.com/hooks/acme",
    "events": [
        "order.paid"
    ],
    "signing_secret": "whsec_5d4c3b2a1908"
}