Managing Endpoints

You can manage serverless endpoints from the dashboard's Endpoints page, the REST API, or the REST client generated into each SDK.

In the dashboard

Open Endpoints in the sidebar.

• Create an endpoint by choosing a platform. For Cloudflare Workers and Vercel, enter the deployment's base URL and the dashboard fills in the healthcheck and trigger URLs. The dialog can also generate a signing secret, which you then set on the endpoint.
• Edit an endpoint to change its URLs or settings, or to rotate its signing secret.
• Disable an endpoint to stop Hatchet from polling it or delivering to it without deleting it. Enable turns it back on.
• Delete an endpoint to remove it.
• Open an endpoint to see its status, the actions it registered, and its Events. See Troubleshooting.

Endpoint fields

Every response also includes status:

• healthy: whether the last healthcheck succeeded. It's absent until the operator has polled the endpoint once.
• error: why the endpoint is unhealthy.
• changedAt: when healthy last changed.
• registeredActions: the action ids registered from the last successful healthcheck.

REST API

All routes take an API token as a bearer token.

curl -X POST \
  -H "Authorization: Bearer $HATCHET_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://cloud.onhatchet.run/api/v1/stable/tenants/$TENANT_ID/serverless/endpoints" \
  -d '{
    "name": "my-endpoint",
    "kind": "CLOUDFLARE_WORKERS",
    "healthcheckUrl": "https://my-worker.my-subdomain.workers.dev/hatchet/healthcheck",
    "triggerUrl": "https://my-worker.my-subdomain.workers.dev/hatchet/trigger",
    "signingSecret": "'"$HATCHET_SIGNING_SECRET"'"
  }'

Creation and updates are validated: a URL that isn't https, has credentials, or names a port other than 443 is refused with 400, as are a signing secret under 32 characters, a setting outside its range, and a duplicate name. A tenant without serverless endpoints enabled gets 403.

From an SDK

import os

from hatchet_sdk import Hatchet
from hatchet_sdk.clients.rest import (
    ApiClient,
    Configuration,
    ServerlessApi,
    V1CreateServerlessEndpointRequest,
    V1ServerlessEndpointKind,
    V1UpdateServerlessEndpointRequest,
)

hatchet = Hatchet()

config = Configuration(
    host=hatchet.config.server_url,
    access_token=hatchet.config.token,
)

with ApiClient(config) as client:
    serverless = ServerlessApi(client)

    # create
    endpoint = serverless.v1_serverless_endpoint_create(
        tenant=hatchet.tenant_id,
        v1_create_serverless_endpoint_request=V1CreateServerlessEndpointRequest(
            name="my-endpoint",
            kind=V1ServerlessEndpointKind.CLOUDFLARE_WORKERS,
            healthcheck_url="https://my-worker.my-subdomain.workers.dev/hatchet/healthcheck",
            trigger_url="https://my-worker.my-subdomain.workers.dev/hatchet/trigger",
            signing_secret=os.environ["HATCHET_SIGNING_SECRET"],
        ),
    )
    endpoint_id = endpoint.metadata.id

    # update: omitted fields keep their values
    serverless.v1_serverless_endpoint_update(
        v1_serverless_endpoint=endpoint_id,
        v1_update_serverless_endpoint_request=V1UpdateServerlessEndpointRequest(
            request_timeout_seconds=300,
        ),
    )

    # recent events, newest first
    events = serverless.v1_serverless_endpoint_event_list(
        v1_serverless_endpoint=endpoint_id,
        limit=20,
    )

    # list and delete
    endpoints = serverless.v1_serverless_endpoint_list(tenant=hatchet.tenant_id)
    serverless.v1_serverless_endpoint_delete(v1_serverless_endpoint=endpoint_id)

Rotating the signing secret

Send a new signingSecret in an update. The API never returns the secret. The operator picks up the new secret on its next refresh of the endpoint, and from then on signs with it. Requests signed with the old secret fail verification on an endpoint that already has the new one, and the other way around. Expect a few failed healthchecks or deliveries while the two sides change over, and update the endpoint and Hatchet close together.

Disabling and deleting

A disabled endpoint isn't polled and receives no tasks, and the operator stops advertising the actions it registered. If no other endpoint or worker serves those actions, their tasks stay queued until one does, subject to their schedule timeout. Deleting an endpoint has the same effect and removes the endpoint for good.