Tài liệu AnyHook

AnyHook không cần SDK hay package nào: bạn thay URL webhook trong dashboard của bên gửi, và handler (đoạn code xử lý webhook trên server của bạn) vẫn nhận đúng những request như trước. Có một điều cần tính trước: các lần thử lại và phát lại mang dấu thời gian (timestamp) gốc của bên gửi, nên với những bên gửi có chữ ký hết hạn (Stripe, Slack và các bên khác có khoảng dung sai trên /providers), kiểm tra AnyHook-Signature để chấp nhận chúng.

Cách nhanh nhất (không cần tài khoản): chạy curl -X POST https://anyhook.net/api/v1/quickstart để nhận ngay một URL nhận (inbound URL) đang hoạt động và một API key, phù hợp cho AI agent và các bài test nhanh. Endpoint này hết hạn sau 7 ngày nếu bạn không nhận nó về tài khoản (claim) qua claim_url được trả về. Trỏ bên gửi về inbound_url được trả về, rồi đọc lại sự kiện bằng GET /api/v1/events và GET /api/v1/events/{id}; trường next_steps trong response có sẵn từng lệnh.

1. 1
   Tạo tài khoản

   Vào anyhook.net/sign-up và tạo một tài khoản miễn phí. Không cần thẻ thanh toán.
2. 2
   Tạo một App

   Một App đại diện cho một nguồn webhook. Tài khoản mới mở ra ngay trên form tạo App: đặt tên (ví dụ “Stripe Production”) và, nếu muốn, nhập URL server của bạn, nơi AnyHook chuyển tiếp từng sự kiện sau khi nhận. Để trống thì App ghi lại mọi thứ mà không chuyển tiếp. Bạn có thể thêm đích bất cứ lúc nào, tối đa 3 đích mỗi App trên gói Free.
3. 3
   Trỏ bên gửi về AnyHook

   Trang App hiển thị URL nhận của bạn và nơi mỗi bên gửi phổ biến yêu cầu nhập nó (ví dụ Stripe → Developers → Webhooks). Dán nó vào đó thay cho URL webhook cũ:

   https://in.anyhook.net/{user-slug}/{app-slug}

   Trang này đang theo dõi: request đầu tiên xuất hiện trên trang trong vài giây. Chưa có gì để gửi? Bấm Send a test event trên cùng trang đó.

Mỗi App có một URL nhận riêng:

https://in.anyhook.net/{user-slug}/{app-slug}

• user-slug: định danh tài khoản của bạn, xem được trong phần cài đặt của dashboard.
• app-slug: riêng cho từng App, tự sinh từ tên App nhưng có thể sửa.

Endpoint nhận chấp nhận mọi request POST, đồng thời trả lời các bước bắt tay xác minh khi thiết lập: một request GET mang hub.mode=subscribe (bước kiểm tra hub.challenge của Meta) được tự động trả lời, kể cả trước khi App được cấu hình. Mọi method khác nhận 405. Trang web và form HTML thông thường cũng có thể post tới endpoint này (xem Code handler). AnyHook trả về HTTP 200 ngay khi sự kiện đã vào hàng đợi bền vững, sau khoảng một giây, dù endpoint đích của bạn nhanh hay chậm, nên bên gửi không bao giờ phải chờ nó.

AnyHook tự nhận diện bên gửi từ các header đến và xác minh chữ ký của payload tại edge (lớp máy chủ biên của Cloudflare). Để bật xác minh, chọn nhà cung cấp webhook khi tạo App và dán webhook signing secret (khóa bí mật dùng để ký) mà nhà cung cấp đưa cho bạn, ví dụ whsec_... của Stripe.

Request không qua được bước kiểm tra bị từ chối tại edge và không bao giờ tới endpoint của bạn. Trang App đếm số request này, và 5 request đầu tiên mỗi ngày được giữ trong nhật ký sự kiện với trạng thái rejected, kèm header và body, để bạn xem vì sao.

AnyHook dùng kiến trúc bất đồng bộ dựa trên hàng đợi để tách bên gửi webhook khỏi backend của bạn:

1. Nhận tại edge: Cloudflare Workers nhận request POST, xác minh chữ ký và trả về 200 khi sự kiện đã được lưu bền vững, sau khoảng một giây.
2. Hàng đợi: sự kiện được đẩy vào một hàng đợi message bền vững (Upstash QStash). Lúc này kết nối HTTP của bên gửi đã đóng.
3. Chuyển tiếp: QStash gửi sự kiện tới bộ chuyển tiếp (forwarder) của AnyHook, nơi POST payload gốc tới endpoint đích của bạn.
4. Ghi nhật ký: mọi bước đều được ghi lại, gồm header/body đến, trạng thái gửi, mã và body phản hồi của endpoint, độ trễ.

Cam kết, nói thẳng ra, vì một dịch vụ trung chuyển mơ hồ về điều nó đảm bảo sẽ đẩy sự mơ hồ đó sang code của bạn:

1. Ít nhất một lần (at-least-once), không phải đúng một lần (exactly-once). Thử lại là cốt lõi của sản phẩm, và một lần thử lại sau khi response bị mất không thể phân biệt với một lượt gửi mới. Thỉnh thoảng bạn sẽ nhận cùng một sự kiện hai lần; không dịch vụ trung chuyển nào hứa khác được, và những bên hứa như vậy chỉ đang mô tả kịch bản suôn sẻ của họ. Handler của bạn phải idempotent (xử lý nhiều lần vẫn cho cùng một kết quả), và ID sự kiện chúng tôi chuyển tiếp trong X-AnyHook-Delivery là khóa để chống trùng lặp.
2. Không đảm bảo thứ tự. Thử lại và gửi đồng thời nghĩa là một sự kiện mới hơn có thể tới trước một sự kiện cũ hơn vẫn đang được thử lại. Phần lớn bên gửi cũng không cam kết thứ tự ngay từ phía họ. Sắp xếp theo một trường bên trong payload (version, updated_at), không bao giờ theo thời điểm đến.
3. Đừng chống trùng lặp dựa trên chữ ký. AnyHook-Signature được ký lại với dấu thời gian mới ở mỗi lần gửi, có chủ ý, để các lần thử lại không bao giờ rơi ra ngoài khoảng dung sai của bạn. Hai lượt gửi của cùng một sự kiện mang hai chữ ký khác nhau; id của sự kiện mới là thứ không đổi.
4. Đã nhận nghĩa là đã lưu bền vững. Edge chỉ trả về 200 sau khi sự kiện đã được lưu, và phía sau hàng đợi còn hai kho dự phòng trước khi edge phải trả 503. Mã 503 từ URL nhận nghĩa là không có gì được lưu, và cơ chế thử lại của chính bên gửi là lưới an toàn, đó là lý do chúng tôi trả 503 thay vì giả vờ.

Khi đích trả về lỗi có thể thử lại hoặc bị timeout, AnyHook tự động thử lại theo exponential backoff (khoảng chờ tăng theo cấp số nhân):

Phản hồi nào dẫn tới thử lại?

Không phải lỗi nào cũng thử lại được. AnyHook phân loại phản hồi của endpoint để không tốn lần gửi, hay hạn mức compute của bạn, vào những lỗi mà thử lại cũng không sửa được:

Mỗi lần gửi được ghi lại kèm toàn bộ body phản hồi và mã trạng thái. Cả lỗi 4xx vĩnh viễn lẫn lỗi có thể thử lại đều được tính cho circuit breaker (cơ chế ngắt mạch): 20 lần thất bại liên tiếp thuộc bất kỳ loại nào sẽ làm nó ngắt.

Thông báo khi thất bại

AnyHook gửi email cảnh báo ở những ngưỡng cụ thể thay vì cho từng sự kiện, để hộp thư của bạn không bị quá tải:

• Lần thất bại thứ 1: cảnh báo ngay, kèm mã trạng thái và đích.
• Lần thất bại liên tiếp thứ 5: cảnh báo leo thang, kèm gợi ý.
• Lần thất bại liên tiếp thứ 20: circuit breaker ngắt (xem bên dưới), gửi cảnh báo circuit breaker.

Một email ở mỗi ngưỡng nêu trên, rồi một email ở mỗi bậc của circuit breaker (mỗi lần tạm dừng và lần vô hiệu hóa), không bao giờ gửi một email cho mỗi sự kiện. Chỉ cần một lượt gửi thành công là bộ đếm được đặt lại.

Nếu AnyHook phát hiện 20 lần gửi thất bại liên tiếp tới cùng một đích (kể cả 4xx vĩnh viễn), circuit breaker ngắt và bắt đầu leo thang theo từng bậc:

Cách hoạt động

• Chiều nhận vẫn hoạt động. URL nhận của bạn luôn hoạt động, sự kiện từ Stripe, GitHub, v.v. vẫn được nhận và lưu. Chỉ chiều gửi đi tới đích của bạn bị tạm dừng.
• Sau mỗi lần tạm dừng hết hạn, AnyHook gửi một lượt thăm dò half-open: sự kiện tiếp theo được dùng để thử đích của bạn. Nếu thành công, mạch đóng lại và mọi thứ được đặt lại.
• Chỉ một lần thành công là mọi thứ được đặt lại: cả số lần thất bại liên tiếp lẫn số lần ngắt đều trở về không.
• Sự kiện nhận được trong lúc tạm dừng được lưu với trạng thái circuit_open và có thể được phát lại khi đích của bạn khôi phục.
• Bạn nhận email thông báo ở mỗi bậc leo thang, kèm URL đích, số lần thất bại và thời gian tạm dừng.
• Nếu đích bị vô hiệu hóa (lần ngắt thứ 5), bạn phải tự bật lại nó trong dashboard.

Cách leo thang từng bậc này cho server của bạn thời gian để khôi phục, đồng thời không để các lần thử lại tới một endpoint đã chết tiêu hao hạn mức compute của bạn.

Mọi sự kiện tới được URL nhận của bạn đều được ghi lại, dù việc gửi nó diễn ra thế nào. Nhật ký bắt đầu từ lúc bạn trỏ nhà cung cấp về AnyHook: một sự kiện đã thất bại trước thời điểm đó chỉ còn ở phía nhà cung cấp (với Stripe, xem cách phát lại một webhook). Mỗi mục nhật ký gồm:

• Toàn bộ header và body đến (đúng như nhận từ bên gửi)
• Trạng thái gửi: queued → success / retrying / failed / rejected / circuit_open / quota_exceeded. rejected nghĩa là AnyHook đã từ chối sự kiện (xác minh chữ ký thất bại, hoặc URL đích bị chặn); sự kiện chưa từng được gửi đi và không thể phát lại.
• Mã và body phản hồi HTTP của đích (theo từng lần gửi)
• Độ trễ tính bằng mili giây
• Số lần gửi và thời điểm thử lại tiếp theo
• Sự kiện có phải là một lần phát lại hay không (is_replay: true)

Thời gian lưu sự kiện tùy theo gói. Free: 3 ngày, phát lại được trong suốt thời gian đó, sau đó bị xóa. Pro: 1 năm: phát lại được trong 30 ngày, sau đó nằm trong kho lưu trữ mã hóa, chỉ đọc. Scale: 7 năm: phát lại được trong 90 ngày, sau đó nằm trong kho lưu trữ mã hóa, chỉ đọc. Enterprise: linh hoạt.

Mọi sự kiện trong nhật ký đều có thể được phát lại từ dashboard bằng một cú bấm. Một lần phát lại gửi payload đã lưu, nguyên từng byte, tới đích mà sự kiện đã được gửi tới, hoặc tới URL mới của đích đó nếu bạn đã đổi nó từ đó tới nay.

• Vào Dashboard → Events
• Tìm sự kiện và bấm Replay
• Một sự kiện mới được tạo với is_replay: true, liên kết với sự kiện gốc

AnyHook dùng được ngay cho phát triển trên máy local, không cần chế độ đặc biệt hay CLI nào. Có hai cách:

1. Chuyển tiếp trực tiếp qua tunnel

Đặt đích của App là một URL tunnel trỏ về máy local của bạn. Nhà cung cấp tunnel nào cũng được:

# ngrok
ngrok http 3000
# → https://abc123.ngrok.io

# cloudflared
cloudflared tunnel --url http://localhost:3000

# localhost.run
ssh -R 80:localhost:3000 nokey@localhost.run

Sao chép URL tunnel vào đích của App trong dashboard. AnyHook chuyển tiếp webhook tới đó giống hệt mọi endpoint khác: thử lại, ghi nhật ký và header chữ ký đều hoạt động như nhau.

2. Ghi lại và phát lại về localhost

Để các sự kiện production thật tích lũy trong AnyHook, rồi phát lại bất kỳ sự kiện nào về môi trường local của bạn khi cần. Không cần tự kích hoạt sự kiện test, test với payload thật, bao nhiêu lần giới hạn phát lại hằng ngày của bạn cho phép.

• Đổi đích sang URL tunnel của bạn
• Mở Dashboard → Events và bấm Replay trên một sự kiện bất kỳ
• Hoặc dùng API: POST /api/v1/events/{id}/replay
• Payload gốc được gửi nguyên từng byte tới đích hiện tại của bạn

Cách này đặc biệt hữu ích khi debug các trường hợp biên: tìm sự kiện gây lỗi trong log production, phát lại nó trên máy local, rồi sửa tới khi handler chạy đúng.

Mọi dữ liệu payload webhook đều được mã hóa khi lưu trữ bằng AES-256-GCM trước khi tới cơ sở dữ liệu. Bao gồm header đến, body của request và signing secret của từng đích.

Mã hóa dùng một khóa riêng (AES_SECRET_KEY), được lưu tách biệt với thông tin đăng nhập cơ sở dữ liệu. Một vụ rò rỉ cơ sở dữ liệu mà không có khóa mã hóa chỉ thu được bản mã: không có dữ liệu webhook dạng rõ, không có signing secret, không có thông tin khách hàng.

AnyHook xác minh chữ ký webhook tại edge của Cloudflare, trước khi sự kiện vào hàng đợi. Khi một App đã có signing secret, request thiếu chữ ký hoặc có chữ ký không hợp lệ bị từ chối bằng mã 401 và không bao giờ tốn hạn mức của bạn; khi chưa có secret, request được chuyển tiếp mà không được xác minh.

Chữ ký được nhận diện tự động dựa trên header. Khi bạn tạo App và chọn loại nguồn, AnyHook lưu signing secret (mã hóa khi lưu trữ) và dùng đúng thuật toán của nhà cung cấp đó.

Nguồn chưa được hỗ trợ hoặc tùy chỉnh

Nếu nguồn webhook của bạn không có trong danh sách được hỗ trợ, chọn Generic khi tạo App. AnyHook sẽ:

• Nhận và đưa vào hàng đợi mọi POST gửi đến, không kiểm tra chữ ký ở chiều vào.
• Chuyển tiếp body nguyên từng byte cùng các header gốc của nhà cung cấp tới đích của bạn, kèm một AnyHook-Signature mới ở mỗi lần gửi. Các header hạ tầng được thêm phía trước edge của chúng tôi (cf-* và các header tương tự) bị loại bỏ.
• Gắn header AnyHook-Signature để endpoint của bạn vẫn xác minh được request đã đi qua AnyHook.

App loại Generic không kiểm tra chữ ký ở chiều vào, dù bạn đặt secret nào. AnyHook-Signature chứng minh request đã đi qua AnyHook, chứ không chứng minh ai đã gửi nó tới AnyHook, nên nếu cần điều đó, giữ phần kiểm tra của riêng bạn trên header gốc của bên gửi (được chuyển tiếp nguyên vẹn). Nếu bên gửi ký theo Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature, như OpenAI và Replicate), chọn nguồn đó thay vào: request sẽ được xác minh tại edge.

Ba thiết lập tùy chọn trên mỗi đích, đều có từ gói Pro trở lên. Đặt chúng trong App → Destinations → Delivery controls, hoặc bằng PATCH /api/v1/apps/{slug} trên đối tượng đích. Tài khoản Free giữ các thiết lập đã đặt khi còn trả phí, nhưng không thay đổi được.

{
  "destinations": [{
    "url": "https://api.example.com/hooks/stripe",
    "event_types": ["invoice.*", "checkout.session.completed"],
    "rate_limit": 20,
    "delay_seconds": 5
  }]
}

Trên gói Pro và Scale, một App có thể chạy code của riêng bạn trên mọi sự kiện nó nhận được, trong một sandbox (môi trường cô lập), không cần server riêng. Lưu code sẽ cho App một đích chạy code đó, nên thử lại, phát lại, circuit breaker và nhật ký sự kiện hoạt động như với mọi đích khác, và output console cùng giá trị trả về của mỗi lượt chạy chính là response của lượt gửi đó. Viết code trong mục Code của App hoặc bằng các endpoint bên dưới. Template cho các tác vụ thường gặp có tại /code-templates.md, và việc chuyển từ Pipedream có hướng dẫn riêng.

export default async function (event, { env, store }) {
  // event: { method, headers, body, raw_body, delivery_id, attempt }
  console.log(event.body);
}

• Sự kiện. body là JSON đã parse, các trường form (urlencoded, hoặc các trường text của một form multipart) hoặc text thô, còn raw_body là text đúng như khi nhận. method luôn là POST; query string, path và IP của bên gọi không được giữ lại. delivery_id là ID X-AnyHook-Delivery của sự kiện, còn attempt đếm từ 1, và bằng 0 ở lượt chạy test.
• Thất bại. Ném lỗi (throw) làm lượt gửi thất bại, và lượt gửi đó được thử lại theo số lần gửi của gói (Lịch thử lại). Lần thử lại của một sự kiện đã chạy thành công sẽ không chạy lại code, nhưng một lượt chạy thất bại sau khi một lệnh gọi đã đi qua thì có, nên hãy dùng delivery_id làm idempotency key cho những lệnh gọi như vậy khi API cho phép.
• Các step của Pipedream. export default defineComponent({ async run({ steps, $ }) {} }) cũng chạy được: steps.trigger.event là sự kiện ở trên, $.export và $.flow.exit hoạt động, mọi prop data_store là kho dữ liệu của App, $auth.field của một app prop đọc secret APP_FIELD, và mọi prop khác đọc secret mang tên của nó (channelId đọc CHANNEL_ID). Hướng dẫn chuyển từ Pipedream liệt kê những gì không mang sang được.
• Package npm. Những gì code import sẽ được cài khi bạn lưu, ghim phiên bản theo cách của Pipedream (import axios from "axios@1.7.9"), tối đa 20 package. Một lần lưu có cài package mới có thể mất vài phút; nếu cài thất bại thì không có gì được lưu.
• Secret. Đọc qua env.NAME hoặc process.env.NAME, tối đa 20 secret, tên gồm chữ cái, chữ số và dấu gạch dưới, không bắt đầu bằng chữ số. PATH, HOME, NODE_OPTIONS, NODE_PATH, PWD và các tên bắt đầu bằng ANYHOOK_ thuộc về runtime, và mỗi giá trị dài tối đa 4.000 ký tự. Giá trị không bao giờ rời khỏi server.
• Kho dữ liệu. store.get, set (kèm { ttl } tính bằng giây), has, delete, keys, entries và clear giữ trạng thái giữa các sự kiện, mỗi App một kho: tối đa 1.000 key, mỗi key dài tối đa 256 ký tự, mỗi giá trị tối đa 64.000 byte ở dạng JSON. Một lần import nhận {"entries": {key: value}}, ghi đè các key đã có và đặt chúng không kèm TTL.
• Lịch hẹn giờ. schedule gồm năm trường cron, theo UTC trừ khi có tiền tố CRON_TZ=Area/City. Mỗi lần kích hoạt sẽ post một sự kiện anyhook.schedule tới URL của chính App, nên nó được tính là một lượt chạy và một sự kiện, và lịch chỉ kích hoạt khi code đang bật. Nguồn của App phải là generic hoặc auto, không có signing secret: dành cho code chạy theo lịch một App riêng.
• Email. Mọi App cũng nhận mail tại {user-slug}.{app-slug}@anyhook.net, dưới dạng sự kiện email.received với body gồm from, to, subject, message_id, date, size và thư MIME ở trường raw. Giống lịch hẹn giờ, nó cần một App có nguồn generic hoặc auto, không có signing secret, và mail vượt giới hạn payload của gói sẽ bị trả lại.
• Trang web và form. Một trang có thể fetch() URL nhận: edge trả lời CORS preflight, và mọi response đều kèm Access-Control-Allow-Origin: *. Một form HTML thông thường cần method="post". Thêm ?redirect=https://your-site.com/thanks vào action của form, và một sự kiện đã được lưu sẽ chuyển người truy cập tới đó bằng mã 303, miễn là địa chỉ đó thuộc trang web đã gửi form; nếu không, người truy cập thấy một trang ngắn “Received”. Các trường text nằm trong event.body; file tải lên sẽ không còn.
• Giới hạn. Code tối đa 64.000 byte, và một lượt chạy được kéo dài 105 giây trên gói Pro và 285 giây trên gói Scale. Mỗi lượt chạy giữ lại 16.000 ký tự cuối cùng của output console. Số lượt chạy mỗi tháng nằm trong bảng gói, và mọi lượt chạy đều được tính, kể cả thử lại, chạy test, phát lại và các lần lịch hẹn giờ kích hoạt. Không có phí vượt hạn mức: khi hết số lượt chạy của tháng, một lượt gửi tới code sẽ nhận 429 và được tạm giữ (circuit_open), không được thử lại, sẵn sàng để phát lại khi sang tháng mới hoặc khi gói được nâng cấp.
• Test, bật và tắt. POST .../code/test chạy code đã lưu trên sự kiện mới nhất đã lưu của App, trên một event_id, hoặc trên một body bạn truyền vào, rồi trả về log, giá trị trả về và thời gian chạy. Nó được tính là một lượt chạy và không gửi gì đi, nhưng những gì chính code gửi đi thì vẫn xảy ra. Sự kiện chỉ chạy code khi code đang bật. Dashboard lưu code mới ở trạng thái tắt, còn PUT .../code lưu phiên bản đầu tiên ở trạng thái bật, trừ khi bạn truyền "enabled": false; các lần lưu sau giữ nguyên trạng thái hiện tại. Trong lúc một đích khác vẫn đang xử lý cùng các sự kiện, như khi đang chuyển đổi, lưu với "enabled": false và bật code sau khi bạn gỡ đích kia. Mỗi thay đổi bật/tắt cần tới một phút để tới mọi vị trí edge.

Mọi request API đều cần một Bearer token trong header Authorization:

Authorization: Bearer ahk_live_xxxxxxxxxxxxxxxx

Tạo API key tại Dashboard → Settings → API Keys. Key gắn với tài khoản của bạn, cho quyền đầy đủ hoặc chỉ đọc (bạn chọn khi tạo), và có thể thu hồi bất cứ lúc nào. Một client kết nối qua đăng nhập MCP (anyhook.net/mcp) có thể gọi cùng các endpoint bằng OAuth access token của nó, trong phạm vi quyền bạn đã cho phép.

AnyHook là một MCP server tại https://anyhook.net/mcp, nên một agent có thể tạo App, đọc nhật ký sự kiện và phát lại các sự kiện thất bại cho bạn, và trên gói Pro và Scale, deploy và test code của một App (anyhook_code_deploy, anyhook_code_test, anyhook_code_get). Claude Code, claude.ai, Codex và VS Code kết nối bằng URL và đăng nhập qua trình duyệt, không cần sao chép key: các bước cho từng client.

Cursor, Windsurf và Claude Desktop dùng key. Tạo một key tại Dashboard → Settings → API Keys, nơi hiển thị đoạn cấu hình này với key của bạn đã điền sẵn:

{
  "mcpServers": {
    "anyhook": {
      "command": "npx",
      "args": [
        "-y",
        "anyhook-mcp"
      ],
      "env": {
        "ANYHOOK_API_KEY": "ahk_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor: Settings → MCP → Add new MCP server, hoặc ~/.cursor/mcp.json. Windsurf: ~/.codeium/windsurf/mcp_config.json. Claude Desktop: Settings → Developer → Edit Config. Các tool code cần anyhook-mcp 0.4.0 trở lên, bản mà npx -y tải về, hoặc server tại https://anyhook.net/mcp.

Sau đó hỏi nó: “Tạo một App AnyHook cho webhook Stripe của tôi và cho tôi URL của nó.” Agent có thể đọc toàn bộ nội dung này trong /llms.txt.

Xem chi tiết bảng giá →