Create webhook

curl --request POST \
  --url https://api.gigstack.io/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-domain.com/webhooks/gigstack",
  "events": [
    "payment.created",
    "payment.succeeded"
  ],
  "description": "Production webhook for payment events",
  "status": "active"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://your-domain.com/webhooks/gigstack',
    events: ['payment.created', 'payment.succeeded'],
    description: 'Production webhook for payment events',
    status: 'active'
  })
};

fetch('https://api.gigstack.io/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/webhooks"

payload = {
    "url": "https://your-domain.com/webhooks/gigstack",
    "events": ["payment.created", "payment.succeeded"],
    "description": "Production webhook for payment events",
    "status": "active"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "message": "Webhook created successfully. Save the secret — it will not be shown again.",
  "data": {
    "id": "wh_dyS2ZVTj",
    "url": "https://your-domain.com/webhooks/gigstack",
    "events": [
      "payment.created",
      "payment.succeeded"
    ],
    "status": "active",
    "description": "Production webhook for payment events",
    "owner": "8UWdgXELUhf022vuoq249mtGytG2",
    "created_at": 1709090576567,
    "secret": "3f9a1c0e7b2d4f6a8c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f5a"
  },
  "timestamp": 1709090576600
}

Webhooks

Create webhook

Create a new webhook endpoint to receive event notifications.

The response includes the webhook’s signing secret. It is shown only once, so store it immediately. It signs only sat.invoice.synced and invoice_batch.completed deliveries, in the X-Gigstack-Signature header (sha256= + hex HMAC-SHA256 of the raw body). Resource events are not signed with it. There is no endpoint to reveal or rotate the secret later; if you lose it, delete the webhook and create a new one.

Webhooks created here send resource events in the v1 format unless your team’s default is v2. Delivery formats, headers and retry behavior are described in the webhookEvent callback below.

gigstack Connect: Create webhooks for other teams using the team parameter.

POST

webhooks

Create webhook

curl --request POST \
  --url https://api.gigstack.io/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-domain.com/webhooks/gigstack",
  "events": [
    "payment.created",
    "payment.succeeded"
  ],
  "description": "Production webhook for payment events",
  "status": "active"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://your-domain.com/webhooks/gigstack',
    events: ['payment.created', 'payment.succeeded'],
    description: 'Production webhook for payment events',
    status: 'active'
  })
};

fetch('https://api.gigstack.io/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/webhooks"

payload = {
    "url": "https://your-domain.com/webhooks/gigstack",
    "events": ["payment.created", "payment.succeeded"],
    "description": "Production webhook for payment events",
    "status": "active"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "message": "Webhook created successfully. Save the secret — it will not be shown again.",
  "data": {
    "id": "wh_dyS2ZVTj",
    "url": "https://your-domain.com/webhooks/gigstack",
    "events": [
      "payment.created",
      "payment.succeeded"
    ],
    "status": "active",
    "description": "Production webhook for payment events",
    "owner": "8UWdgXELUhf022vuoq249mtGytG2",
    "created_at": 1709090576567,
    "secret": "3f9a1c0e7b2d4f6a8c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f5a"
  },
  "timestamp": 1709090576600
}

Authorizations

Authorization

string

header

required

Authentication Method: HTTP Bearer token.

The runtime requires the literal Bearer prefix — a bare token in the Authorization header is rejected with 401 unauthorized.

Header Format: Authorization: Bearer YOUR_API_KEY

Your API key is a JWT. Live keys operate on live data (livemode: true); test keys operate on isolated test data (livemode: false).

Get your key at: app.gigstack.pro/settings?tab=api

Errors: credential failures are answered by the authentication layer with a raw { "message": … } body, not the standardized envelope — 401 for a missing, malformed or expired token, 403 for a revoked key or a plan without API access. See the Unauthorized and AuthForbidden responses.

Query Parameters

team

string

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a team other than the one your API key belongs to return 403 without it.

Only API keys can use it: an OAuth access token sent with another team's id is rejected with 403 Team mismatch with OAuth token.

Optional — omit it entirely unless you are acting on another team. It deliberately carries no example value so generated snippets do not emit ?team=undefined; when the parameter is absent, the team is derived from your API key.

Example: ?team=team_xyz789

Body

application/json

Unknown top-level keys are rejected (400 validation_failed / unexpected_key) — body validation runs in strict allowlist mode. team, livemode and owner are reserved and injected by the auth middleware.

url

string<uri>

required

Endpoint URL that receives the events. Any valid URL is accepted; use HTTPS in production

Example:

"https://your-domain.com/webhooks/gigstack"

events

enum<string>[]

required

Array of event types to subscribe to (at least one required)

Minimum array length: 1

Available options:

payment.created,

payment.updated,

payment.succeeded,

payment.canceled,

payment.deleted,

payment.upcoming_due_date,

invoice.created,

invoice.canceled,

invoice.failed,

invoice_batch.completed,

receipt.created,

receipt.updated,

receipt.completed,

receipt.deleted,

customer.created,

customer.updated,

customer.deleted,

service.created,

service.updated,

service.deleted,

sat.invoice.synced

Example:

["payment.created", "payment.succeeded"]

description

string | null

Optional description of the webhook purpose

Example:

"Production webhook for payment events"

status

enum<string> | null

default:active

Webhook status - defaults to active

Available options:

active,

inactive,

null

Example:

"active"

Callbacks

POST

{$request.body#/url}webhookEvent

Body

application/json

Option 1
Option 2
Option 3
Option 4

Body of a webhook delivery (Content-Type: application/json). There are three formats:

Resource events (payment.*, invoice.*, receipt.*, customer.*, service.*) use the webhook's payload version:
- WebhookPayloadV1: the default for webhooks created with POST /webhooks.
- WebhookPayloadV2: for webhooks created or last saved in the gigstack dashboard, or on teams whose default is v2.
sat.invoice.synced always uses SatInvoiceSyncedWebhookEvent.
invoice_batch.completed always uses InvoiceBatchCompletedWebhookEvent.

Tell them apart by shape:

v2 has type and data.object.
v1 has event, team and webhook.
The SAT and batch events have event and created_at; read event to tell them apart.

event

enum<string>

required

Event type a webhook can subscribe to.

Available options:

payment.created,

payment.updated,

payment.succeeded,

payment.canceled,

payment.deleted,

payment.upcoming_due_date,

invoice.created,

invoice.canceled,

invoice.failed,

invoice_batch.completed,

receipt.created,

receipt.updated,

receipt.completed,

receipt.deleted,

customer.created,

customer.updated,

customer.deleted,

service.created,

service.updated,

service.deleted,

sat.invoice.synced

Example:

"sat.invoice.synced"

team

string

required

Team that owns the webhook.

Example:

"team_1234567890"

webhook

string

required

ID of the webhook receiving this delivery.

Example:

"wh_dyS2ZVTj"

livemode

boolean

required

false for test-mode resources.

Example:

true

data

object

required

The resource at the moment of the event, in gigstack's internal (camelCase) format. metadata values are sent as strings.

connectedTeam

string

Only on deliveries to a gigstack Connect master team. The connected team the event came from.

connectedTeamMetadata

object

Only with connectedTeam, when that team has metadata. Values are strings.

Show child attributes

Response

200

Any 2xx acknowledges the delivery.

For resource events, 408, 429 and 5xx trigger a retry, and any other 4xx is final.
For sat.invoice.synced and invoice_batch.completed the response is ignored.

Response

Webhook created successfully

success

boolean

Example:

true

message

string

Example:

"Webhook created successfully. Save the secret — it will not be shown again."

data

object

The created webhook, plus its signing secret. The secret is returned only in this response.

Show child attributes

timestamp

integer<int64>

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Create webhook

Authorizations

Query Parameters

Body

Callbacks

Body

Response

Response