Management

Create a webhook endpoint

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

Registers an endpoint Firsty delivers the chosen event types to. The response is the only time the signing secret is returned. A client can have up to 5 endpoints, active or not.

post/management/webhooks

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Request body

application/json · required

urlstring · urirequired

Destination Firsty posts events to.

eventTypesarray of stringrequired

Values from GET /catalog/webhook-event-types.

descriptionstring

Free-text label for the endpoint.

Responses

201The created endpoint, with its signing secretapplication/json

Show response body

dataobjectrequired

Show properties

webhookEndpointReferencestringrequired

Identifies the endpoint in GET /management/webhooks/{webhookEndpointReference}/deliveries.

urlstring · urirequired

Destination Firsty posts events to.

eventTypesarray of stringrequired

Event types delivered to this endpoint. Values this client subscribed to before an event type was retired are returned as stored, so an entry may be absent from GET /catalog/webhook-event-types.

descriptionstring | nullrequired

Free-text label for the endpoint.

activebooleanrequired

Whether events are delivered to this endpoint.

createdAtstring · date-timerequired

updatedAtstring · date-timerequired

signingSecretstringrequired

Key that signs every delivery to this endpoint. Returned only by create and rotate-secret.

409The client already has 3 webhook endpointsapplication/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 429Rate limit exceeded 500Internal server error

Request

curl https://connect.firsty.app/api/v3/management/webhooks \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://partner.example.com/firsty/webhooks",
  "eventTypes": [
    "package.created",
    "package.usage.threshold"
  ],
  "description": "Production"
}'

fetch('https://connect.firsty.app/api/v3/management/webhooks', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://partner.example.com/firsty/webhooks',
    eventTypes: ['package.created', 'package.usage.threshold'],
    description: 'Production'
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/management/webhooks",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "url": "https://partner.example.com/firsty/webhooks",
      "eventTypes": [
        "package.created",
        "package.usage.threshold"
      ],
      "description": "Production"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/management/webhooks', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json'
  ],
  'json' => [
    'url' => 'https://partner.example.com/firsty/webhooks',
    'eventTypes' => [
      'package.created',
      'package.usage.threshold'
    ],
    'description' => 'Production'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/management/webhooks"

	payload := strings.NewReader(`{
  "url": "https://partner.example.com/firsty/webhooks",
  "eventTypes": [
    "package.created",
    "package.usage.threshold"
  ],
  "description": "Production"
}`)

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

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

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/management/webhooks"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"url\": \"https://partner.example.com/firsty/webhooks\",\n  \"eventTypes\": [\n    \"package.created\",\n    \"package.usage.threshold\"\n  ],\n  \"description\": \"Production\"\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

curl https://connect.test.firsty.app/api/v3/management/webhooks \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://partner.example.com/firsty/webhooks",
  "eventTypes": [
    "package.created",
    "package.usage.threshold"
  ],
  "description": "Production"
}'

fetch('https://connect.test.firsty.app/api/v3/management/webhooks', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://partner.example.com/firsty/webhooks',
    eventTypes: ['package.created', 'package.usage.threshold'],
    description: 'Production'
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/management/webhooks",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "url": "https://partner.example.com/firsty/webhooks",
      "eventTypes": [
        "package.created",
        "package.usage.threshold"
      ],
      "description": "Production"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/management/webhooks', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json'
  ],
  'json' => [
    'url' => 'https://partner.example.com/firsty/webhooks',
    'eventTypes' => [
      'package.created',
      'package.usage.threshold'
    ],
    'description' => 'Production'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/management/webhooks"

	payload := strings.NewReader(`{
  "url": "https://partner.example.com/firsty/webhooks",
  "eventTypes": [
    "package.created",
    "package.usage.threshold"
  ],
  "description": "Production"
}`)

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

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

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/management/webhooks"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"url\": \"https://partner.example.com/firsty/webhooks\",\n  \"eventTypes\": [\n    \"package.created\",\n    \"package.usage.threshold\"\n  ],\n  \"description\": \"Production\"\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "webhookEndpointReference": "K7Q2M9XA",
    "url": "https://partner.example.com/firsty/webhooks",
    "eventTypes": [
      "package.created",
      "package.usage.threshold"
    ],
    "description": "Production",
    "active": true,
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "signingSecret": "string"
  }
}

{
  "type": "https://developers.firsty.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A client can have at most 5 webhook endpoints."
}