Skip to content

Commit 8a8abe2

Browse files
louisachulouisachu
committed
test with less content
1 parent 6084082 commit 8a8abe2

File tree

1 file changed

+146
-1
lines changed

1 file changed

+146
-1
lines changed

‎src/pages/guides/index.md

Lines changed: 146 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,152 @@ description: With Adobe I/O Events webhooks, your application can sign up to be
1010
---
1111

1212
import RetryDoc from '../common/retry-doc.md'
13+
import ReceivingEventsForUsersDoc from '../common/receiving-events-for-users-doc.md'
1314

1415
# Introduction to Adobe I/O Events Webhooks
1516

16-
<RetryDoc/>
17+
With Adobe I/O Events webhooks, your application can sign up to be notified whenever certain events occur.
18+
For example, when a user uploads a asset, this action generates an event.
19+
With the right webhook in place, your application is instantly notified that this event happened.
20+
21+
Please refer to the `Adobe Developer Console` documentation on how to [Add Events to a project](/developer-console/docs/guides/services/services-add-event/)
22+
23+
To start receiving events, you create an event registration specifying a webhook URL and the types of events you want to receive. Each event will result in a HTTP request to the given URL, notifying your application. This guide provides an introduction to webhooks.
24+
25+
## Getting started
26+
27+
An **Event** is a JSON object that describes something that happened. Events originate from **Event Providers**. Each event provider publishes specific types of events, identified by an **Event Code**. A **Webhook URL** receives event JSON objects as HTTP POST requests. You start receiving events by creating an **Event Registration**, providing a name, description, webhook URL, and a list of **Event Types** you are interested in.
28+
29+
### Webhook example
30+
31+
Acme Inc. wants to be notified when a new file is uploaded to Adobe Creative Cloud Assets, so it creates the following event registration:
32+
33+
```json
34+
{
35+
"name": "Acme Webhook",
36+
"description": "Listen for newly created files",
37+
"webhook_url": "https://acme.example.com/webhook",
38+
"events_of_interest": [
39+
{
40+
"provider": "ccstorage",
41+
"event_code": "asset_created"
42+
}
43+
]
44+
}
45+
```
46+
47+
Now when a file is uploaded, Adobe I/O Events performs the following HTTP request:
48+
49+
```http
50+
POST https://acme.example.com/webhook HTTP/1.1
51+
content-type: application/json
52+
53+
{
54+
"@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b",
55+
"@type": "xdmCreated",
56+
"xdmEventEnvelope:objectType": "xdmAsset",
57+
"activitystreams:published": "2016-07-16T19:20:30+01:00",
58+
"activitystreams:to": {
59+
"xdmImsOrg:id": "08B3E5CE5822FC520A494229@AdobeOrg",
60+
"@type": "xdmImsOrg"
61+
},
62+
"activitystreams:generator": {
63+
"xdmContentRepository:root": "http://francois.corp.adobe.com:4502/",
64+
"@type": "xdmContentRepository"
65+
},
66+
"activitystreams:actor": {
67+
"xdmAemUser:id": "admin",
68+
"@type": "xdmAemUser"
69+
},
70+
"activitystreams:object": {
71+
"@type": "xdmAsset",
72+
"xdmAsset:asset_id": "urn:aaid:aem:4123ba4c-93a8-4c5d-b979-ffbbe4318185",
73+
"xdmAsset:asset_name": "Fx_DUKE-small.png",
74+
"xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e",
75+
"xdmAsset:path": "/content/dam/Fx_DUKE-small.png",
76+
"xdmAsset:format": "image/png"
77+
},
78+
"@context": {
79+
"activitystreams": "http://www.w3.org/ns/activitystreams#",
80+
"xdmEventEnvelope": "https://ns.adobe.com/xdm/common/eventenvelope#",
81+
"xdmAsset": "http://ns.adobe.com/xdm/assets/asset#",
82+
"xdmImsOrg": "https://ns.adobe.com/xdm/ims/organization#",
83+
"xdmContentRepository": "https://ns.adobe.com/xdm/content/repository",
84+
"xdmAemUser": "https://ns.adobe.com/xdm/aem/user#",
85+
"xdmCreated": "https://ns.adobe.com/xdm/common/event/created#"
86+
}
87+
}
88+
```
89+
90+
## Your first webhook
91+
92+
Before you can register a webhook, the webhook needs to be online and operational. If not, then the event registration will fail. So you need to take care of setting that up first. Your webhook must be hosted on a server. For development, you may use [webhook.site](https://webhook.site), but ensure you complete the [asynchronous validation](#asynchronous-validation) for it to be considered functional.
93+
94+
For production, your webhook needs to:
95+
96+
- Be accessible from the internet (not using localhost)
97+
- Be reachable over HTTPS
98+
- Correctly respond to a "challenge" request
99+
100+
### The challenge request
101+
102+
#### Synchronous validation
103+
104+
When creating an event registration using a webhook, Adobe I/O Events will first try to verify that the URL is valid. To do this, it sends an HTTP GET request, with a `challenge` query parameter. The webhook should respond with a body containing the value of the `challenge` query parameter.
105+
106+
##### Request
107+
108+
```http
109+
GET https://acme.example.com/webhook?challenge=8ec8d794-e0ab-42df-9017-e3dada8e84f7
110+
```
111+
112+
##### Response
113+
114+
You can either respond by placing the challenge value directly in the response body:
115+
116+
```http
117+
HTTP/1.1 200 OK
118+
119+
"8ec8d794-e0ab-42df-9017-e3dada8e84f7"
120+
```
121+
122+
or by responding with a JSON object, including the correct `content-type` header:
123+
124+
```http
125+
HTTP/1.1 200 OK
126+
Content-type: application/json
127+
128+
{"challenge":"8ec8d794-e0ab-42df-9017-e3dada8e84f7"}
129+
```
130+
131+
Typically, you would build your webhook to respond to the Adobe challenge in a method to handle HTTP GET requests, and then include another method for handling the HTTP POST requests that will be coming from Adobe containing actual event payloads. For testing purposes, you can start with something as simple as this PHP script:
132+
133+
```php
134+
<?php
135+
header('Content-Type: text/plain');
136+
echo $_GET['challenge'];
137+
?>
138+
```
139+
140+
**Note:** Make sure your response is given in the correct content type. If your webhook script places the challenge value directly in the response body, make sure it's returned as plain text (`text/plain`). For a JSON response, make sure it's `application/json`. Returning a response in the incorrect content type may cause extraneous code to be returned, which will not validate with Adobe I/O Events.
141+
142+
#### Asynchronous validation
143+
144+
When the webhook fails to respond appropriately to the challenge request, Adobe I/O Events sends an HTTP POST request with a body containing a custom URL for manual validation.
145+
146+
```http
147+
POST https://acme.example.com/webhook HTTP/1.1
148+
content-type: application/json
149+
150+
{"validationUrl": "https://csm.adobe.io/csm/registrations/validate?id=<guid1>&challenge=<guid2>"}
151+
```
152+
153+
To complete verification, you need to send a GET request to it using a web browser/cURL or any simple REST client.
154+
155+
```bash
156+
curl -L -X GET 'https://csm.adobe.io/csm/registrations/validate?id=<guid1>&challenge=<guid2>'
157+
```
158+
159+
The custom URL is valid for **5 minutes**. If the validation is not completed within 5 minutes, your event registration is marked `Disabled`.
160+
161+
Your webhook must respond to the POST request with an HTTP status code of 200 before it can be put in the asynchronous validation mode. In other words, if the webhook responds with a 200, but doesn't respond with a body containing the challenge, it is switched to asynchronous validation mode. If there is a GET request on the validation URL within 5 minutes, the event registration is marked `Active`.

0 commit comments

Comments
 (0)