You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/cre/guides/workflow/using-http-client/index.mdx
+11-20Lines changed: 11 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,32 +20,23 @@ The CRE SDK provides an HTTP client that allows your workflows to interact with
20
20
21
21
{/* prettier-ignore */}
22
22
<Asidetype="caution"title="Parse responses before aggregation">
23
-
When using a numeric aggregation method (such as `median`), always parse the HTTP response **inside** your node function and return a numeric value — never pass the raw response body to the aggregation step. If your endpoint returns an error string and your node function passes that string to a median aggregation, consensus will fail with `unsupported type for median aggregation`. See the [best practices section](/cre/guides/workflow/using-http-client/get-request#best-practices) of the GET request guide for correct and incorrect patterns.
23
+
When using a numeric aggregation method (such as `median`), always parse the HTTP response **inside** your node function and return a numeric value: never pass the raw response body to the aggregation step. If your endpoint returns an error string and your node function passes that string to a median aggregation, consensus will fail with `unsupported type for median aggregation`. See the [best practices section](/cre/guides/workflow/using-http-client/get-request#best-practices) of the GET request guide for correct and incorrect patterns.
24
24
</Aside>
25
25
26
-
These guides will walk you through the common use cases for the HTTP client.
26
+
## Guides
27
+
28
+
-**[Making GET Requests](/cre/guides/workflow/using-http-client/get-request)**: Learn how to fetch data from a public API using a `GET` request.
29
+
-**[Making POST Requests](/cre/guides/workflow/using-http-client/post-request)**: Learn how to send data to an external endpoint using a `POST` request.
30
+
-**[Submitting Reports via HTTP](/cre/guides/workflow/using-http-client/submitting-reports-http)**: Learn how to submit cryptographically signed reports to an external HTTP endpoint.
31
+
-**[Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain)**: Verify report signatures and read workflow metadata when receiving reports over HTTP or other offchain channels.
27
32
28
33
## CRE reports over HTTP
29
34
30
35
A **CRE report** is a DON-signed package your workflow creates with `runtime.report()` (TypeScript) or `runtime.GenerateReport()` (Go). It contains your encoded payload, workflow metadata, and cryptographic signatures.
31
36
32
-
Most secure HTTP integrations involve two parties:
33
-
34
-
**Sender workflow (CRE):** runs on a schedule or trigger, does your logic, then creates and ships the report:
35
-
36
-
1. Run business logic and encode your payload.
37
-
2. Call `runtime.report()` / `GenerateReport()` so the DON signs the report.
38
-
3. Call `sendReport()` to POST the report to your URL.
37
+
A typical secure integration uses two parties:
39
38
40
-
**Receiver:** a separate system that gets that HTTP POST (your API, or another CRE workflow with an HTTP trigger):
39
+
1.**Sender:** a CRE workflow that runs your logic, signs a report, and POSTs it to a URL. See [Submitting Reports via HTTP](/cre/guides/workflow/using-http-client/submitting-reports-http).
40
+
2.**Receiver:** your API or another CRE workflow that verifies the report before using the data. See [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain).
41
41
42
-
4. Verify signatures with `Report.parse()` / `ParseReport()`, then use the payload. See [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain).
43
-
44
-
The sender **creates** the report in step 2; you do not fetch it from somewhere else first. The receiver **must** verify before trusting the data: the sender does not do that for you.
45
-
46
-
## Guides
47
-
48
-
-**[Making GET Requests](/cre/guides/workflow/using-http-client/get-request)**: Learn how to fetch data from a public API using a `GET` request.
49
-
-**[Making POST Requests](/cre/guides/workflow/using-http-client/post-request)**: Learn how to send data to an external endpoint using a `POST` request.
50
-
-**[Submitting Reports via HTTP](/cre/guides/workflow/using-http-client/submitting-reports-http)**: Learn how to submit cryptographically signed reports to an external HTTP endpoint.
51
-
-**[Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain)**: Verify report signatures and read workflow metadata when receiving reports over HTTP or other offchain channels.
42
+
The sender creates the report inside the workflow; the receiver must verify signatures before trusting the payload.
@@ -41,8 +41,6 @@ This guide is for the **sender** side: a CRE workflow that **creates** a signed
41
41
3.`runtime.GenerateReport()`: DON produces a signed `sdk.ReportResponse`.
42
42
4.`SendReport()`: format and POST to your URL.
43
43
44
-
For a conceptual overview, see [API Interactions: CRE reports over HTTP](/cre/guides/workflow/using-http-client#cre-reports-over-http).
45
-
46
44
## Prerequisites
47
45
48
46
- Familiarity with [making POST requests](/cre/guides/workflow/using-http-client/post-request)
@@ -54,9 +52,21 @@ For a conceptual overview, see [API Interactions: CRE reports over HTTP](/cre/gu
54
52
HTTP requests to URLs that return redirects (3xx status codes) will fail. Ensure the URL you provide is the final destination and does not redirect to another URL.
55
53
</Aside>
56
54
57
-
## Quick start: Minimal example
55
+
## Payload contract (if you verify offchain)
56
+
57
+
Receivers using [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go) expect JSON with hex fields **without**`0x`. Use JSON key `context` for `reportContext`:
58
+
59
+
| JSON field | SDK field on `ReportResponse`|
60
+
| ------------ | ----------------------------- |
61
+
|`report`|`RawReport`|
62
+
|`context`|`ReportContext`|
63
+
|`signatures`| per-node signatures in `Sigs`|
64
+
65
+
## Quick start: Minimal example (binary only)
58
66
59
-
Here's the simplest possible workflow that generates and submits a report via HTTP:
67
+
Posts **raw `RawReport` bytes** only. Not compatible with the verify guide’s JSON receiver. For local testing, use the [complete working example](#complete-working-example) or [Pattern 4 for offchain verification (hex)](#pattern-4-for-offchain-verification-hex).
68
+
69
+
Here's the simplest workflow that generates and submits a report via HTTP:
Use when testing [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go). The verify examples decode **hex without `0x`** in JSON. Base64 Pattern 4 above does not match unless you change the receiver.
You'll notice that all the patterns above include `CacheSettings`. This is critical for report submissions, just like it is for [POST requests](/cre/guides/workflow/using-http-client/post-request).
1. Check webhook.site to see the report data received
599
+
1. On webhook.site, open **Content** and confirm JSON with `report`, `context`, and `signatures` (hex). Use that JSON to test a receiver workflow in [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go#testing-locally-with-simulation).
600
+
601
+
## Next step: verify on the receiver
602
+
603
+
The sender does not validate the report for the receiver. After submission, the ingesting side must verify signatures before trusting the payload. See [Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go).
-**[API Interactions: CRE reports over HTTP](/cre/guides/workflow/using-http-client#cre-reports-over-http):** sender → receiver overview
592
-
-**[Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go):** receiver workflow; verify before trusting payload
670
+
-**[Verifying CRE Reports Offchain](/cre/guides/workflow/using-http-client/verifying-reports-offchain-go):** verify signatures on the receiver before trusting payload data
593
671
-**[HTTP Client SDK Reference](/cre/reference/sdk/http-client):** complete API reference including `SendReport` and `sdk.ReportResponse`
594
672
-**[POST Requests](/cre/guides/workflow/using-http-client/post-request):** HTTP request patterns and caching
595
673
-**[Generating Reports: Single Values](/cre/guides/workflow/using-evm-client/onchain-write/generating-reports-single-values):** create reports from single values
0 commit comments