|
1 | | -# webhook-component |
| 1 | +# Webhook Component |
2 | 2 | ## Table of Contents |
3 | 3 |
|
4 | | -* [General information](#general-information) |
5 | | - * [Description](#description) |
6 | | - * [Purpose](#purpose) |
| 4 | +* [Description](#description) |
7 | 5 | * [Credentials](#credentials) |
8 | 6 | * [Triggers](#triggers) |
9 | 7 | * [Receive](#receive) |
|
12 | 10 | * [Known Limitations](#known-limitations) |
13 | 11 |
|
14 | 12 | ## Description |
15 | | -### Purpose |
16 | | -An open source component for sending and receiving [WebHooks](https://en.wikipedia.org/wiki/Webhook) on [elastic.io platform](https://www.elastic.io "elastic.io platform"). |
| 13 | +The Webhook component receives data at the specified URL to initiate your workflow. |
17 | 14 |
|
18 | 15 | ## Credentials |
19 | | -Webhook component supports the following authorisation types: |
20 | | -* **No Auth** - use this method to work with any open REST API |
21 | | -* **Basic Auth** - use it to provide login credentials like username/password |
22 | | -* **API Key Auth** - use it to provide API Key to access the resource |
23 | | -* **HMAC verification shared secret** - use it to verify via a shared secret |
24 | | - |
25 | | - |
| 16 | +The Webhook component supports the following authorization methods: |
| 17 | + |
| 18 | +* **No Auth** - Use this method to interact with any open REST API. |
| 19 | +* **Basic Auth** - Utilize this method to provide login credentials. This method includes the following fields: |
| 20 | + * **Username** - (string, required) |
| 21 | + * **Password** - (string, required) |
| 22 | +* **API Key Auth** - Use this method to provide an API key as part of the headers to access the resource. This method includes the following fields: |
| 23 | + * **Header Name** - (string, required) |
| 24 | + * **Header Value** - (string, required) |
| 25 | +* **HMAC (sha256/sha512) verification with shared secret** - Use this method to verify requests using a shared secret. This method includes the following fields: |
| 26 | + * **Header Name** - (string, optional, defaults to `x-eio-signature`) |
| 27 | + * **HMAC (sha256/sha512) verification shared secret** - (string, required) |
26 | 28 |
|
27 | 29 | ## Triggers |
28 | | - ### Receive |
29 | | - Simple webhook trigger which receives data as an input and starts the flow execution after this. |
30 | | - |
31 | | - #### Expected output metadata |
32 | | - [Output schema](lib/schemas/base64.out.json) |
33 | | - |
34 | | - Example: |
35 | | - ```metadata json |
| 30 | +### Receive |
| 31 | +This is a simple webhook trigger that receives data as input and initiates the execution of the workflow. |
| 32 | + |
| 33 | +#### Output Metadata |
| 34 | +The message body emitted from the webhook will contain: |
| 35 | +* A JSON object that was transferred using the `POST` method or query parameters in the case of a `GET` request. |
| 36 | +* `_query` (object) - Contains the query parameters. |
| 37 | +* `_headers` (object) - Contains the headers of the received request. |
| 38 | +* `_method` (string, `POST` or `GET`) - Indicates the HTTP method of the received request. |
| 39 | +* `_url` (string) - The full URL that was received. |
| 40 | + |
| 41 | +#### Webhook Response |
| 42 | +By default, the webhook URL will respond with the following structure: |
| 43 | +```json |
36 | 44 | { |
37 | | - "recievedBody": "recievedBody", |
38 | | - "_query": {}, |
39 | | - "_headers": { |
40 | | - "content-type": "application/json", |
41 | | - "accept": "*/*", |
42 | | - "accept-encoding": "gzip, deflate" |
43 | | - }, |
44 | | - "_method": "POST", |
45 | | - "_url": "/hook/5d691738cb5a286adc1e68e2" |
46 | | - } |
| 45 | + "requestId": "86ad47dfbce4a8ae8a1eb505b85d8bd5", |
| 46 | + "message": "thank you" |
| 47 | +} |
47 | 48 | ``` |
48 | 49 |
|
49 | | -## Actions |
50 | | - ### Send data |
51 | | - Simply sends data it receives as an input to a URL provided. |
52 | | - |
53 | | - WebHook action can also be used to troubleshoot many processes to see the outcome. |
54 | | - For example one could create Invoices (in Salesforce) to Webhook flow and configure the Webhook with a url created in https://webhook.site or with any similar services. |
55 | | - |
56 | | - #### List of Expected Config fields |
57 | | - * **[required]** **HTTP Verb** |
58 | | - * **POST**. The WebHook component can POST information to preconfigured WebHook address. This action could be used for different purposes. For example WebHook can be used to inform your custom connector about an event which it waits to work. |
59 | | - * **PUT**. The WebHook component can also PUT a specific preconfigured JSON into specific address where the process will not be handled by the server. For this reason the "Output JSON Sample" field can be used. |
60 | | - * **[required]** **URI**. This is the address to send WebHook. |
61 | | - * **[not required]** **Secret**. This is an optional field to authenticate WebHook POST. There maybe cases when a special password or a secret might be required. For example the WebHook address was generated explicitly with a password so that to prevent any third parties to use it. This could be your specific WebHook address that you use to send your Wordpress posts into your server. |
62 | | - |
63 | | -  |
64 | | - |
65 | | - #### Expected output metadata |
66 | | - [Output schema](lib/schemas/base64.out.json) |
67 | | - |
68 | | - Example: |
69 | | - ```metadata json |
70 | | - { |
71 | | - "recievedBody": "recievedBody", |
72 | | - "_query": {}, |
73 | | - "_headers": { |
74 | | - "content-type": "application/json", |
75 | | - "accept": "*/*", |
76 | | - "accept-encoding": "gzip, deflate" |
77 | | - }, |
78 | | - "_method": "POST", |
79 | | - "_url": "/hook/5d691738cb5a286adc1e68e2" |
80 | | - } |
81 | | - ``` |
82 | | - |
83 | | -## Known limitations |
| 50 | +However, you can specify the exact content of the reply using the [HTTP Reply](https://docs.elastic.io/components/request-reply/index.html) component. In this case, you will receive a reply only when the message reaches the step where the `HTTP Reply` is used, or if an error occurs in other steps between the `Webhook` step and the `HTTP Reply`. |
84 | 51 |
|
85 | | -1. Maximal possible size for an attachment is 10 MB. |
86 | | -2. Attachments mechanism does not work with [Local Agent Installation](https://support.elastic.io/support/solutions/articles/14000076461-announcing-the-local-agent-) |
| 52 | +## Known Limitations |
| 53 | +* Currently, the component supports the following HTTP methods: `POST` and `GET`. |
| 54 | +* When using a `POST` request, only `JSON` or `XML` data can be transferred to the workflow; other types, such as text or files, are not supported. |
| 55 | +* `XML` data will be automatically converted to `JSON` format. |
| 56 | +* The base path of the URL begins with the keyword `hook` followed by the flow ID, for example, `/hook/678119de28021e00129641fe`. You can append the desired path only after this base path, such as `/hook/678119de28021e00129641fe/sales/orders`. |
0 commit comments