Webhook Endpoints

Webhook endpoints accept POST requests from external services and store the JSON payload in a configured table. The webhook id is checked against AllowedColumns, the payload is inserted unchanged with a UTC timestamp, and the response returns the new row id.

Database setup ​

SQL Server table:

CREATE TABLE [dbo].[WebhookData] (
    [Id]         INT IDENTITY(1,1) PRIMARY KEY,
    [WebhookId]  NVARCHAR(255)    NOT NULL,
    [Payload]    NVARCHAR(MAX)    NOT NULL,
    [ReceivedAt] DATETIME         NOT NULL DEFAULT GETDATE()
);

CREATE INDEX IX_WebhookData_WebhookId
ON [dbo].[WebhookData] ([WebhookId], [ReceivedAt] DESC);

Equivalent tables for the other providers. PostgreSQL column names are quoted because they are case-sensitive:

CREATE TABLE public."WebhookData" (
    "Id"         SERIAL PRIMARY KEY,
    "WebhookId"  VARCHAR(255) NOT NULL,
    "Payload"    TEXT         NOT NULL,
    "ReceivedAt" TIMESTAMPTZ  NOT NULL DEFAULT now()
);

CREATE TABLE WebhookData (
    Id         INT AUTO_INCREMENT PRIMARY KEY,
    WebhookId  VARCHAR(255) NOT NULL,
    Payload    LONGTEXT     NOT NULL,
    ReceivedAt DATETIME     NOT NULL
);

CREATE TABLE WebhookData (
    Id         INTEGER PRIMARY KEY AUTOINCREMENT,
    WebhookId  TEXT NOT NULL,
    Payload    TEXT NOT NULL,
    ReceivedAt TEXT NOT NULL
);

The ReceivedAt value is stored in UTC.

Optional status columns for the processing job:

ALTER TABLE WebhookData ADD
    ProcessedAt DATETIME     NULL,
    RetryCount  INT          NOT NULL DEFAULT 0,
    LastError   NVARCHAR(MAX) NULL;

Configuration ​

Example with namespace Webhooks and endpoint name Incoming:

{
  "DatabaseObjectName": "WebhookData",
  "DatabaseSchema": "dbo",
  "AllowedColumns": [
    "payment_webhook",
    "shipping_webhook",
    "inventory_webhook"
  ]
}

AllowedColumns lists the accepted webhook ids; other ids return 404. The id is stored in the WebhookId column. All properties: Entity configuration.

Sending webhooks ​

POST /api/{environment}/{namespace}/{name}/{webhookId}

POST /api/prod/Webhooks/Incoming/payment_webhook
Content-Type: application/json
Authorization: Bearer <token>

{
  "event": "payment.success",
  "payment_id": "pay_123456",
  "amount": 99.99,
  "currency": "EUR",
  "timestamp": "2024-03-15T10:30:00Z"
}

Response (201 Created):

{
  "success": true,
  "message": "Webhook processed successfully.",
  "result": null,
  "id": 12345
}

Querying stored payloads ​

Field extraction with SQL Server JSON functions:

-- Recent payloads for one webhook type
SELECT TOP 10
    Id,
    JSON_VALUE(Payload, '$.event')      AS EventType,
    JSON_VALUE(Payload, '$.payment_id') AS PaymentId,
    ReceivedAt
FROM WebhookData
WHERE WebhookId = 'payment_webhook'
ORDER BY ReceivedAt DESC;

Limitations ​

• POST only
• JSON payloads only; other bodies are rejected
• No validation beyond JSON syntax and the webhook id
• No retry on insert failure
• No forwarding; a separate job or procedure processes the table
• Payload size limit: 10MB (default)
• Tenancy is not supported

Troubleshooting ​

Debug logging: Log levels.