1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
//! The wire contract of `webhook_receive` — a public inbound endpoint any
//! plugin can have, whatever its `kind`.
//!
//! A field-for-field mirror of internal/extwasm/webhook.go's
//! `WebhookRequest`/`WebhookResponse`.
//!
//! # Why this exists
//!
//! Until it did, only `kind = "channel"` and `kind = "chatops"` plugins
//! could be *told* anything: each had a webhook whose meaning was fixed by
//! its kind (an inbound chat message; a reply in a mirrored thread). Every
//! other kind — the crm/erp/msp/issue_tracker/custom connectors that are
//! this SDK's main use — could only ask its vendor questions when an agent
//! happened to open a ticket. An ERP pushing "invoice paid", a tracker
//! pushing "issue closed", a monitoring system pushing an alert: none had
//! anywhere to deliver, and adding one meant a Go change inside Salamandr
//! per vendor. Which is the dependency this SDK exists to remove.
//!
//! # How to use it
//!
//! Declare `webhook = true` under `[scopes]` and list `"webhook_receive"`
//! in `entrypoints` — the manifest is refused at install if the two
//! disagree, in either direction. Register the handler in the
//! **`context_ops`** block: its wire shape is `context_ops`' exactly (the
//! host decodes your answer directly, and an [`OpError`](crate::OpError)
//! becomes a real envelope-level failure), and unlike an action it is
//! never reachable from a browser click, so it needs no `action_ops`-style
//! allow-list.
//!
//! After install, the admin panel shows the delivery URL to paste into the
//! vendor. The token in it is host-minted and rotatable; that rotation is
//! the only revocation there is.
//!
//! # The host does not read your payload
//!
//! It hands you the request verbatim and sends back whatever
//! [`WebhookResponse`] you return. Whatever the delivery should *change*,
//! do during the call through the host functions your manifest already
//! grants: [`crate::core`] to add a note or a tag, [`crate::kv_set`] to
//! remember state, [`crate::http_fetch`] to call the vendor back. A host
//! that parsed payloads would need to know every vendor, and nobody who
//! writes a plugin would be able to add one.
//!
//! # Verify the sender yourself
//!
//! The URL token authenticates the *route*, not the caller: it proves the
//! delivery reached the right tenant and plugin, and nothing about who
//! sent it. If your vendor signs its deliveries, check that signature here
//! — read the shared secret with [`crate::get_config`] and compare it
//! against the relevant header before acting. The host cannot do this for
//! you without knowing each vendor's scheme.
//!
//! ```no_run
//! use salamandr_plugin_sdk::{OpError, WebhookRequest, WebhookResponse, WebhookResult};
//!
//! fn webhook_receive(req: WebhookRequest) -> WebhookResult {
//! // Endpoint-verification handshakes are GETs that echo a challenge.
//! if req.method == "GET" {
//! return Ok(WebhookResponse::text(req.query_param("challenge").unwrap_or_default()));
//! }
//! let payload: serde_json::Value = serde_json::from_str(&req.body)
//! .map_err(|e| OpError::Other(format!("invalid payload: {e}")))?;
//! let _event = payload["event"].as_str().unwrap_or_default();
//! // ... react through core/kv/http_fetch ...
//! Ok(WebhookResponse::default())
//! }
//! ```
use ;
use crateOpError;
/// WebhookRequest is one delivery, verbatim.
/// WebhookResponse is what gets sent back to the vendor.
///
/// Default is an empty 200, which is what most deliveries want. The other
/// two cases are a challenge echo during endpoint verification, and a
/// deliberate non-200 to make a vendor retry later.
///
/// `content_type` is honoured only for `application/json` and
/// `text/plain`; anything else is served as `text/plain`. That is not an
/// oversight — this body is returned to an unauthenticated caller on the
/// helpdesk's own origin, so a plugin-chosen `text/html` would be a
/// stored-XSS primitive.
/// WebhookResult is `webhook_receive`'s return type.
///
/// An `Err` is a real failure: it is logged server-side and the vendor
/// gets a bare 200, so it will not retry. If you want a retry, answer
/// `Ok(WebhookResponse::status(503))` instead — the distinction is
/// deliberate, since "I could not process this" and "please send it again"
/// are different things and only the plugin knows which applies.
pub type WebhookResult = ;