Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

extension-http-endpoints

/extension-http-endpoints

Obsługuje przychodzące żądania HTTP w kanisterze Motoko (webhooki, boty, API zdrowia) przez metody IC HTTP Gateway http_request i http_request_update, na przykład dla Stripe czy Telegrama.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
22.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
10
Przestarzałość

Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Obsługuje przychodzące żądania HTTP w kanisterze Motoko (webhooki, boty, API zdrowia) przez metody IC HTTP Gateway http_request i http_request_update, na przykład dla Stripe czy Telegrama.

Oryginalny opis (EN)

Serve inbound HTTP from a Motoko canister (webhooks, curl POST/GET, bot callbacks, ingest/health APIs) via the IC HTTP Gateway methods `http_request` / `http_request_update`. Load whenever the user or spec needs a canister URL that external HTTP clients can hit — Stripe/GitHub/Slack webhooks, Telegram bots, health checks, or any plain REST-ish endpoint. NOT for calling external APIs from the canister (use `extension-http-outcalls`); NOT for certified static asset serving.

Jak działa

  1. When to use which skill
  2. How inbound HTTP works
  3. Rules of thumb
  4. How to curl
  5. Related
  6. Local PocketIC (limitations)
Sekcje z nagłówków SKILL.md, w oryginale · 154 linii, 853 słów
Podgląd SKILL.md
---
name: extension-http-endpoints
description: >-
  Serve inbound HTTP from a Motoko canister (webhooks, curl POST/GET, bot
  callbacks, ingest/health APIs) via the IC HTTP Gateway methods
  `http_request` / `http_request_update`. Load whenever the user or spec needs
  a canister URL that external HTTP clients can hit — Stripe/GitHub/Slack
  webhooks, Telegram bots, health checks, or any plain REST-ish endpoint.
  NOT for calling external APIs from the canister (use
  `extension-http-outcalls`); NOT for certified static asset serving.
version: 0.2.1
compatibility:
  mops:
    caffeineai-http-endpoints: "~0.1.0"
    caffeineai-authorization: "~1.0.1"
caffeineai-subscription: [none]
---

# HTTP Endpoints (inbound)

Inbound HTTP for [Caffeine AI](https://caffeine.ai?utm_source=caffeine-skill&utm_medium=referral) Motoko backends via `mo:caffeineai-http-endpoints`.

## When to use which skill

| Need | Skill |
| --- | --- |
| External client (`curl`, webhook, bot) hits the canister over HTTPS | **this skill** |
| Canister calls an external HTTPS API | [`extension-http-outcalls`](../extension-http-outcalls/SKILL.md) |
| Typed OpenAI / Google / X / Stripe client | the matching domain skill (those wrap **outbound** calls) |

Do not implement inbound handlers with the management-canister `http_request` / `Call.httpRequest` outcall API — that is the opposite direction.

## How inbound HTTP works

1. Client hits the **backend** Motoko canister over HTTPS (not `*.caffeine.xyz`, custom domain, or frontend/asset canister).
2. The HTTP Gateway calls `http_request` (**query**).
3. Mutating routes return `Http.upgrade()` so the gateway re-issues as `http_request_update` (**update**).

**URLs**

- **Webhooks / POST:** `https://<backend-canister-id>.icp0.io/...` (or `.ic0.app`)
- **Uncertified GET (health / plaintext):** `https://<backend-canister-id>.raw.icp0.io/...` — non-raw gateways expect certified query bodies (out of scope)

# Backend

Use the prefabricated modules (do not modify them):

```mo:caffeineai-http-endpoints/Http
module {
  public type Request = { method : Text; url : Text; headers : [HeaderField]; body : Blob; certificate_version : ?Nat16 };
  public type Response = { status_code : Nat16; headers : [HeaderField]; body : Blob; streaming_strategy : ?StreamingStrategy; upgrade : ?Bool };

  public func path(url : Text) : Text;
  public func header(req : Request, name : Text) : ?Text; // case-insensitive
  public func text(status : Nat16, body : Text) : Response;
  public func upgrade() : Response; // query path asks gateway to call http_request_update
  public func notFound() : Response;
  public func methodNotAllowed() : Response;
  public func bodyText(req : Request) : ?Text; // null if body is not UTF-8; HMAC must use req.body
};
```

```mo:caffeineai-http-endpoints/MixinHttpEndpoints
mixin (
  onQuery : Http.Request -> Http.Response,
  onUpdate : Http.Request -> async Http.Response,
) {
  public query func http_request(req : Http.Request) : async Http.Response;
  public func http_request_update(req : Http.Request) : async Http.Response;
};
```

Add `mops add caffeineai-http-endpoints`. Wire handlers on the **existing** actor in `main.mo` — keep `MixinAuthorization`, do not replace the actor or redeclare `http_request*`.

`onQuery` must stay query-safe: no awaits, no state writes. Mutating work belongs in `onUpdate` after `Http.upgrade()` from the query path.

```motoko filepath=src/backend/main.mo
import Http "mo:caffeineai-http-endpoints/Http";
import MixinHttpEndpoints "mo:caffeineai-http-endpoints/MixinHttpEndpoints";
import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";

actor {
  let accessControlState : AccessControl.AccessControlState;
  include MixinAuthorization(accessControlState, null);

  func onHttpQuery(req : Http.Request) : Http.Response {
    let path = Http.path(req.url);
    if (req.method == "POST" and path == "/webhook") {
      return Http.upgrade();
    };
    if (req.method == "GET" and (path == "/" or path == "/health")) {
      return Http.text(200, "ok");
    };
    Http.notFound();
  };

  func onHttpUpdate(req : Http.Request) : async Http.Response {
    let path = Http.path(req.url);
    if (req.method == "POST" and path == "/webhook") {
      // Signature checks: Http.header(req, "stripe-signature"), HMAC over req.body
      ignore Http.bodyText(req);
      return Http.text(200, "received");
    };
    Http.notFound();
  };

  include MixinHttpEndpoints(onHttpQuery, onHttpUpdate);
};
```

The migration chain head:

```motoko filepath=src/backend/migrations/00000000_000000.mo
import AccessControl "mo:caffeineai-authorization/access-control";

module {
  type NewActor = {
    accessControlState : AccessControl.AccessControlState;
  };

  public func migration(_old : {}) : NewActor {
    { accessControlState = AccessControl.initState() };
  };
};
```

## Rules of thumb

- **Mutations only in `onUpdate`.** Query returns `Http.upgrade()` for POST/PUT/PATCH/DELETE routes that write.
- **Backend canister id only** for webhook URLs — project/frontend origins never reach Motoko `http_request`.
- **Uncertified GET → `.raw.icp0.io`.** Do not invent response certificates.
- **Prefer Candid + React** for app UI; use inbound HTTP only for external HTTP clients.
- **Auth:** no IC caller principal from webhook senders — verify signatures/secrets yourself (`Http.header`, raw `req.body`).
- **Large JSON:** keep payloads small/schema-simple, or store the blob and process elsewhere.

## How to `curl`

Uncertified GET on a non-raw host is a hard gateway failure (`503` / `backend_response_verification` / `Certification values not found`), not a 404 from your handler. POSTs that return `Http.upgrade()` skip that check.

```bash
# Reads — must be raw
curl https://<backend-canister-id>.raw.icp0.io/health

# Writes — non-raw is fine (update path)
curl -X POST https://<backend-canister-id>.icp0.io/webhook \
  -H 'content-type: application/json' \
  -H 'x-webhook-secret: …' \
  -d '{"event":"…"}'
```

`?canisterId=<id>` on `https://icp0.io/...` is an alternate host form. Prefer the canister subdomain. An IP/`localhost` GET with only `?canisterId=` can return an empty `204` instead of your body — treat that as the wrong URL shape, not an empty handler.

## Related

- [`extension-http-outcalls`](../extension-http-outcalls/SKILL.md) — canister → internet (module helpers, no inbound mixin)
- [`extension-stripe`](../extension-stripe/SKILL.md) — checkout via outcalls; inbound Stripe webhooks still use this skill
- [icskills#337](https://github.com/dfinity/icskills/issues/337) — upstream skill-gap discussion

## Local PocketIC (limitations)

PocketIC is useful for proving the upgrade dance, not as a drop-in `curl` replica.

- The `pocket-ic` binary is a **control server**. It does not listen for `curl` until a client (`@dfinity/pic`) creates an instance (include an NNS subnet) and calls `makeLive()`, which returns a **port**.
- There is no `mops` one-liner that prints a curl URL. The gateway dies with that Node/pic process.
- Once live, the same rules apply:
  - `http://<canister-id>.raw.localhost:<port>/health` — uncertified GET
  - `http://127.0.0.1:<port>/notes?canisterId=<id>` — POST / upgrade (worked in a live gateway test)
  - `http://<canister-id>.localhost:<port>/health` (no `.raw`) — `503` certification failure
- Do not document PocketIC as the way users hit production webhooks. Production URLs are the `*.icp0.io` / `*.raw.icp0.io` forms above.

Wersje

W bazie nie ma innych skilli o nazwie extension-http-endpoints.

Migawka bazy z 13.11.2026 · wersja paczki b5d099c79391 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100stable-memory
    Utrwala stan kanistra przy aktualizacjach w Rust i Motoko, czyli StableBTreeMap, MemoryManager i hooki aktualizacji.
  • 95rest-api-designer
    Projektuje endpointy REST: modelowanie zasobów, metody HTTP i strukturę adresów URL.
  • 100using-webhooks
    Wyjaśnia, jak działa dostęp do webhooków w aplikacjach Major i jak wdrożyć endpointy odbierające callbacki od usług, np. Stripe.
  • 91writing-motoko
    Podpowiada pułapki języka Motoko, nowoczesną składnię i wzorce architektury dla Internet Computer, przy pisaniu kanistrów i naprawie błędów kompilatora.
  • 95api-gateway
    Wywołuje API zewnętrznych usług, takich jak Slack, HubSpot, Salesforce, Google Workspace i Stripe, przez bramę z zarządzanym uwierzytelnianiem.
  • 100convex-http-actions
    Dodaje endpointy HTTP w convex/http.ts: odbiorniki webhooków z weryfikacją podpisu, trasy w stylu REST, CORS, nagłówki uwierzytelniania, odpowiedzi strumieniowe i wysyłanie plików, na przykład dla Stripe, Clerk czy Resend.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.