post-private-webhooks.h (8173B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file src/include/taler/merchant/post-private-webhooks.h 19 * @brief C interface for the POST /private/webhooks endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_WEBHOOKS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_WEBHOOKS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the POST /private/webhooks request. 30 */ 31 enum TALER_MERCHANT_PostPrivateWebhooksOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_END = 0, 37 38 /** 39 * Set the header template. 40 */ 41 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_HEADER_TEMPLATE, 42 43 /** 44 * Set the body template. 45 */ 46 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_BODY_TEMPLATE 47 48 }; 49 50 51 /** 52 * Value for an option for the POST /private/webhooks request. 53 */ 54 struct TALER_MERCHANT_PostPrivateWebhooksOptionValue 55 { 56 57 /** 58 * Type of the option being set. 59 */ 60 enum TALER_MERCHANT_PostPrivateWebhooksOption option; 61 62 /** 63 * Specific option value. 64 */ 65 union 66 { 67 68 /** 69 * Value if @e option is 70 * #TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_HEADER_TEMPLATE. 71 */ 72 const char *header_template; 73 74 /** 75 * Value if @e option is 76 * #TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_BODY_TEMPLATE. 77 */ 78 const char *body_template; 79 80 } details; 81 82 }; 83 84 85 /** 86 * Handle for a POST /private/webhooks request. 87 */ 88 struct TALER_MERCHANT_PostPrivateWebhooksHandle; 89 90 91 /** 92 * Response details for a POST /private/webhooks request. 93 */ 94 struct TALER_MERCHANT_PostPrivateWebhooksResponse 95 { 96 97 /** 98 * HTTP response details. 99 */ 100 struct TALER_MERCHANT_HttpResponse hr; 101 102 }; 103 104 105 /** 106 * Set up POST /private/webhooks operation. 107 * Note that you must explicitly start the operation after 108 * possibly setting options. 109 * 110 * @param ctx the context 111 * @param url base URL of the merchant backend 112 * @param webhook_id identifier for the new webhook 113 * @param event_type event type that triggers this webhook 114 * @param notification_url URL to send notifications to 115 * @param http_method HTTP method to use for notifications 116 * @return handle to operation 117 */ 118 struct TALER_MERCHANT_PostPrivateWebhooksHandle * 119 TALER_MERCHANT_post_private_webhooks_create ( 120 struct GNUNET_CURL_Context *ctx, 121 const char *url, 122 const char *webhook_id, 123 const char *event_type, 124 const char *notification_url, 125 const char *http_method); 126 127 128 /** 129 * Terminate the list of the options. 130 * 131 * @return the terminating object of struct TALER_MERCHANT_PostPrivateWebhooksOptionValue 132 */ 133 #define TALER_MERCHANT_post_private_webhooks_option_end_() \ 134 (const struct TALER_MERCHANT_PostPrivateWebhooksOptionValue) \ 135 { \ 136 .option = TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_END \ 137 } 138 139 /** 140 * Set header template. 141 * 142 * @param ht header template string to set 143 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateWebhooksOptionValue 144 */ 145 #define TALER_MERCHANT_post_private_webhooks_option_header_template(ht) \ 146 (const struct TALER_MERCHANT_PostPrivateWebhooksOptionValue) \ 147 { \ 148 .option = \ 149 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_HEADER_TEMPLATE, \ 150 .details.header_template = (ht) \ 151 } 152 153 /** 154 * Set body template. 155 * 156 * @param bt body template string to set 157 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateWebhooksOptionValue 158 */ 159 #define TALER_MERCHANT_post_private_webhooks_option_body_template(bt) \ 160 (const struct TALER_MERCHANT_PostPrivateWebhooksOptionValue) \ 161 { \ 162 .option = \ 163 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_OPTION_BODY_TEMPLATE, \ 164 .details.body_template = (bt) \ 165 } 166 167 168 /** 169 * Set the requested options for the operation. 170 * 171 * If any option fail other options may be or may be not applied. 172 * 173 * @param ppwh the request to set the options for 174 * @param num_options length of the @a options array 175 * @param options an array of options 176 * @return #GNUNET_OK on success, 177 * #GNUNET_NO on failure, 178 * #GNUNET_SYSERR on internal error 179 */ 180 enum GNUNET_GenericReturnValue 181 TALER_MERCHANT_post_private_webhooks_set_options_ ( 182 struct TALER_MERCHANT_PostPrivateWebhooksHandle *ppwh, 183 unsigned int num_options, 184 const struct TALER_MERCHANT_PostPrivateWebhooksOptionValue *options); 185 186 187 /** 188 * Set the requested options for the operation. 189 * 190 * If any option fail other options may be or may be not applied. 191 * 192 * It should be used with helpers that create required options, for example: 193 * 194 * TALER_MERCHANT_post_private_webhooks_set_options ( 195 * ppwh, 196 * TALER_MERCHANT_post_private_webhooks_option_header_template ( 197 * "Content-Type: application/json")); 198 * 199 * @param ppwh the request to set the options for 200 * @param ... the list of the options, each option must be created 201 * by helpers TALER_MERCHANT_post_private_webhooks_option_NAME(VALUE) 202 * @return #GNUNET_OK on success, 203 * #GNUNET_NO on failure, 204 * #GNUNET_SYSERR on internal error 205 */ 206 #define TALER_MERCHANT_post_private_webhooks_set_options(ppwh,...) \ 207 TALER_MERCHANT_post_private_webhooks_set_options_ ( \ 208 ppwh, \ 209 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 210 ((const struct TALER_MERCHANT_PostPrivateWebhooksOptionValue[]) \ 211 {__VA_ARGS__, TALER_MERCHANT_post_private_webhooks_option_end_ () } \ 212 )) 213 214 215 #ifndef TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_RESULT_CLOSURE 216 /** 217 * Type of the closure used by 218 * the #TALER_MERCHANT_PostPrivateWebhooksCallback. 219 */ 220 #define TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_RESULT_CLOSURE void 221 #endif /* TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_RESULT_CLOSURE */ 222 223 /** 224 * Callback for a POST /private/webhooks request. 225 * 226 * @param cls closure 227 * @param wpr response details 228 */ 229 typedef void 230 (*TALER_MERCHANT_PostPrivateWebhooksCallback)( 231 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_RESULT_CLOSURE *cls, 232 const struct TALER_MERCHANT_PostPrivateWebhooksResponse *wpr); 233 234 235 /** 236 * Start POST /private/webhooks operation. 237 * 238 * @param[in,out] ppwh operation to start 239 * @param cb function to call with the merchant's result 240 * @param cb_cls closure for @a cb 241 * @return status code, #TALER_EC_NONE on success 242 */ 243 enum TALER_ErrorCode 244 TALER_MERCHANT_post_private_webhooks_start ( 245 struct TALER_MERCHANT_PostPrivateWebhooksHandle *ppwh, 246 TALER_MERCHANT_PostPrivateWebhooksCallback cb, 247 TALER_MERCHANT_POST_PRIVATE_WEBHOOKS_RESULT_CLOSURE *cb_cls); 248 249 250 /** 251 * Cancel POST /private/webhooks operation. This function must not be 252 * called by clients after the TALER_MERCHANT_PostPrivateWebhooksCallback 253 * has been invoked (as in those cases it'll be called internally by the 254 * implementation already). 255 * 256 * @param[in] ppwh operation to cancel 257 */ 258 void 259 TALER_MERCHANT_post_private_webhooks_cancel ( 260 struct TALER_MERCHANT_PostPrivateWebhooksHandle *ppwh); 261 262 263 #endif /* _TALER_MERCHANT__POST_PRIVATE_WEBHOOKS_H */