ManagementExperimental

Create a webhook endpoint

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

dataobject

Show properties

webhookEndpointReferencestring

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

urlstring · uri

Destination Firsty posts events to.

eventTypesarray of string

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 | null

Free-text label for the endpoint.

activeboolean

Whether events are delivered to this endpoint.

createdAtstring · date-time

updatedAtstring · date-time

signingSecretstring

Key that signs every delivery to this endpoint: whsec_ followed by base64. The HMAC key is the base64-decoded bytes after the prefix. Returned only by create and rotate-secret.

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

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundport_in_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancenumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.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": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

{
  "type": "https://developers.firsty.app/errors/validation_failed",
  "code": "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.",
  "code": "conflict"
}