Webhook HTTP API

The routes exposed by SESAR Webhook, their bodies and their response codes. Response property names are in PascalCase, and null properties are omitted.

SESAR request

The processing routes expect the body that SESAR sends, as application/json:

{
  "args": {
    "HashKey": "<authentication value>",
    "CryptedObject": "<encrypted manifest, in Base64>"
  }
}

An empty body or invalid JSON receives a 400 error, before any processing.

Processing response

The single routes return an IntegrationResult:

Property	Type	Role
`Success`	boolean	Processing result
`Message`	text	Summary
`ErrorDetails`	text	Failure details; can contain a raw response from the target system or a stack trace
`ConnectorId`	text	Connector or handler that processed the drop
`Timestamp`	UTC date	Date of the result
`ExternalReferenceId`	text	Reference in the target system, for example the identifier of the record created
`Metadata`	object	Additional data, for example `HandlerId` and `HandlerVersion`
`ItemsProcessed`, `ItemsFailed`	integers	Counters filled in by the connector

Processing routes

POST /api/webhook/handler/{handlerId}

Processes the drop with a handler. It is the recommended address.

Code	When
200	Processing succeeded (`Success` is `true`)
400	Body without `args`
401	Invalid `HashKey`
404	Unknown handler. This check happens before the `HashKey` check.
500	Failure of the processing, of the decryption or of reading the manifest, or application badly initialized

POST /api/webhook/{connectorId}

Processes the drop with a built-in connector. POST /api/webhook, without an identifier, uses DefaultConnectorId.

Code	When
200	Processing succeeded
400	Body without `args`
404	Unknown connector, before the `HashKey` check
500	Processing failure, invalid `HashKey` (`Message`: `Authentication failed`), or application badly initialized

On this route, an invalid HashKey therefore receives 500, not 401.

Multiple routes

Route	Processing	Response
`POST /api/webhook/multi?connectors=id1,id2`	Connectors one after the other	Always 200: `{"Success": true, "Results": [...]}`, even if all failed, including for an invalid `HashKey`
`POST /api/webhook/handler/multi?handlers=id1,id2`	Handlers in parallel	200: `{"Success", "TotalHandlers", "Processed", "Failed", "Results"}`. `Success` is `true` if all identifiers are known and at least one was processed, whatever the result. `Failed` only counts unknown identifiers. 401 if the `HashKey` is invalid.

Avoid these routes with SESAR:

they answer 200 even on failure, so SESAR never sends a badly processed drop again;
connectors= does not strip spaces: write id1,id2, not id1, id2;
a connector never called before through its own address is created there without its settings, and fails.

Management routes

Warning

These routes require no authentication. Reserve them to the server or your administration network: see Secure the deployment.

Route	Response
`GET /api/connectors`	List of ConnectorInfo, `generic` connector included. `IsEnabled` reflects the `Enabled` key, without effect on processing; `IsConfigured` is always `false`.
`GET /api/connectors/{id}`	The connector, or 404
`POST /api/connectors/{id}/test`	200: `{"Success", "Message", "ConnectorId"}`, with `Error` on an exception. Triggers the connector's authentication calls.
`GET /api/handlers`	List `{"HandlerId", "DisplayName", "Description", "Version", "IsEnabled", "WebhookUrl"}`
`GET /api/handlers/{id}`	The handler, or 404
`POST /api/handlers/{id}/test`	200: `{"Success", "Message", "HandlerId"}`, with `Error` on an exception. Calls `ValidateConfigurationAsync`, then `TestConnectionAsync`.
`POST /api/handlers/rescan`	Reads the default handlers folder again, ignoring `HandlersPath`: `{"Success", "Message", "Handlers"}`
`GET /api/health`	Always `{"Status": "Healthy", "Timestamp": "..."}`, even if the application cannot process anything
`GET /api/health/status`	Detailed state: initialization (`ProcessorInitialized`, `InitializationError`), secrets file diagnostics, connectors

Debug routes

Active only if EnableDebugEndpoints is true. Otherwise, they answer 400. Never turn them on in production: they process a plain-text manifest, without a HashKey.

Route	Role
`GET /api/debug/sample-manifest`	An empty manifest, to complete for your tests
`POST /api/debug/connector/{connectorId}`	Processes the plain-text manifest received in the body, without the `args` envelope
`POST /api/debug/handler/{handlerId}`	Same thing with a handler

Table of Contents