Webhook¶

Endpoints

POST      /integrations/:id/webhook

A webhook integration lets an external system push data to Everysk. Each JSON body posted to the integration's webhook URL is stored and starts the workflows that are triggered by that integration, the same way a file received by an email integration does.

To use it:

Create a Webhook integration in the Integrations page of the Everysk platform.
Copy the integration's Webhook URL. It always looks like this: https://api.everysk.com/v2/integrations/intg_aBcDeFgHiJkLmNoPqRsTuVwXy/webhook.
Create a workflow whose trigger is the integration (Integration File Received) and select the webhook integration. See The Worker structure for the workflow triggers.
Configure the external system to POST a JSON object to the webhook URL.

Send a webhook payload¶

To send a payload to a webhook integration, run the following:

Curl

curl https://api.everysk.com/v2/integrations/intg_aBcDeFgHiJkLmNoPqRsTuVwXy/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "event": "positions_ready",
        "date": "2026-10-01",
        "items": [
          {"symbol": "AAPL", "quantity": 100},
          {"symbol": "MSFT", "quantity": 50}
        ]
      }' \
  -X POST

The above call returns the following JSON object:

{
  "integration_id": "intg_aBcDeFgHiJkLmNoPqRsTuVwXy",
  "message": "Webhook payload stored successfully."
}

The whole body is stored as it was sent. There is no fixed schema: any JSON object with at least one key is accepted.

HTTP Request

POST /integrations/:id/webhook

HTTP Parameters

Parameter	Description
`id` string	REQUIRED The webhook integration's unique identifier. An integration's `id` will always look like this: `intg_aBcDeFgHiJkLmNoPqRsTuVwXy`.
`key` string	optional The auth token of one of your API keys, sent on the query string. Use it only when the sender cannot set an `Authorization` header.
body object	REQUIRED The payload. It must be a JSON object with at least one key. Lists, empty objects and bodies that are not JSON are refused.

Authentication¶

The webhook endpoint accepts the same credentials as the rest of the API, sent in the Authorization header:

An OAuth2 access token: Authorization: Bearer <ACCESS_TOKEN>.
An API key: Authorization: Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN, or the same pair with HTTP Basic Authentication.

Some senders cannot set headers. For those, the endpoint also accepts the auth token of an API key on the query string:

Curl

curl "https://api.everysk.com/v2/integrations/intg_aBcDeFgHiJkLmNoPqRsTuVwXy/webhook?key=YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "positions_ready"}' \
  -X POST

Note

The key query string is accepted only on POST /integrations/:id/webhook. Every other endpoint answers 401 to it.
When an Authorization header is present, the header is used and key is ignored.
The account SID is not needed with key, only the auth token.
Treat a webhook URL that carries key as a secret: anyone who has it can post to the integration.

Errors¶

Besides the errors every endpoint can return, the webhook answers:

Code	When
`400`	The body is not a JSON object with content, or the integration is not a webhook integration.
`401`	The credentials are missing or invalid, including a `key` that is not a valid auth token.
`404`	The integration does not exist or does not belong to your account.

Read the payload in a worker¶

When a payload is stored, the workflows triggered by the integration start, and the first worker receives two script inputs:

Input	Description
`body` object	The JSON object that was posted to the webhook, as it was sent.
`date` string	The date and time when the payload was stored.

A custom worker reads them in handle_inputs():

from everysk.sdk.worker_base import WorkerBase


class MyWebhookWorker(WorkerBase):
    body = None

    def handle_inputs(self):
        self.body = self.script_inputs.body
        self.received_at = self.script_inputs.date

    def handle_tasks(self):
        self.items = self.body.get('items', [])

    def handle_outputs(self):
        return {'items': self.items}

See Worker Base for more information about workers.