1 <?php
2
3 namespace PayPal\Api;
4
5 use PayPal\Common\PayPalResourceModel;
6 use PayPal\Exception\PayPalConnectionException;
7 use PayPal\Rest\ApiContext;
8 use PayPal\Transport\PayPalRestCall;
9 use PayPal\Validation\ArgumentValidator;
10 use PayPal\Validation\JsonValidator;
11
12 /**
13 * Class WebhookEvent
14 *
15 * A webhook event notification.
16 *
17 * @package PayPal\Api
18 *
19 * @property string id
20 * @property string create_time
21 * @property string resource_type
22 * @property string event_version
23 * @property string event_type
24 * @property string summary
25 * @property \PayPal\Common\PayPalModel resource
26 * @property string status
27 * @property mixed[] transmissions
28 */
29 class WebhookEvent extends PayPalResourceModel
30 {
31 /**
32 * The ID of the webhook event notification.
33 *
34 * @param string $id
35 *
36 * @return $this
37 */
38 public function setId($id)
39 {
40 $this->id = $id;
41 return $this;
42 }
43
44 /**
45 * The ID of the webhook event notification.
46 *
47 * @return string
48 */
49 public function getId()
50 {
51 return $this->id;
52 }
53
54 /**
55 * The date and time when the webhook event notification was created.
56 *
57 * @param string $create_time
58 *
59 * @return $this
60 */
61 public function setCreateTime($create_time)
62 {
63 $this->create_time = $create_time;
64 return $this;
65 }
66
67 /**
68 * The date and time when the webhook event notification was created.
69 *
70 * @return string
71 */
72 public function getCreateTime()
73 {
74 return $this->create_time;
75 }
76
77 /**
78 * The name of the resource related to the webhook notification event.
79 *
80 * @param string $resource_type
81 *
82 * @return $this
83 */
84 public function setResourceType($resource_type)
85 {
86 $this->resource_type = $resource_type;
87 return $this;
88 }
89
90 /**
91 * The name of the resource related to the webhook notification event.
92 *
93 * @return string
94 */
95 public function getResourceType()
96 {
97 return $this->resource_type;
98 }
99
100 /**
101 * The version of the event.
102 *
103 * @param string $event_version
104 *
105 * @return $this
106 */
107 public function setEventVersion($event_version)
108 {
109 $this->event_version = $event_version;
110 return $this;
111 }
112
113 /**
114 * The version of the event.
115 *
116 * @return string
117 */
118 public function getEventVersion()
119 {
120 return $this->event_version;
121 }
122
123 /**
124 * The event that triggered the webhook event notification.
125 *
126 * @param string $event_type
127 *
128 * @return $this
129 */
130 public function setEventType($event_type)
131 {
132 $this->event_type = $event_type;
133 return $this;
134 }
135
136 /**
137 * The event that triggered the webhook event notification.
138 *
139 * @return string
140 */
141 public function getEventType()
142 {
143 return $this->event_type;
144 }
145
146 /**
147 * A summary description for the event notification. For example, `A payment authorization was created.`
148 *
149 * @param string $summary
150 *
151 * @return $this
152 */
153 public function setSummary($summary)
154 {
155 $this->summary = $summary;
156 return $this;
157 }
158
159 /**
160 * A summary description for the event notification. For example, `A payment authorization was created.`
161 *
162 * @return string
163 */
164 public function getSummary()
165 {
166 return $this->summary;
167 }
168
169 /**
170 * The resource that triggered the webhook event notification.
171 *
172 * @param \PayPal\Common\PayPalModel $resource
173 *
174 * @return $this
175 */
176 public function setResource($resource)
177 {
178 $this->resource = $resource;
179 return $this;
180 }
181
182 /**
183 * The resource that triggered the webhook event notification.
184 *
185 * @return \PayPal\Common\PayPalModel
186 */
187 public function getResource()
188 {
189 return $this->resource;
190 }
191
192 /**
193 * Validates Received Event from Webhook, and returns the webhook event object. Because security verifications by verifying certificate chain is not enabled in PHP yet,
194 * we need to fallback to default behavior of retrieving the ID attribute of the data, and make a separate GET call to PayPal APIs, to retrieve the data.
195 * This is important to do again, as hacker could have faked the data, and the retrieved data cannot be trusted without either doing client side security validation, or making a separate call
196 * to PayPal APIs to retrieve the actual data. This limits the hacker to mimick a fake data, as hacker wont be able to predict the Id correctly.
197 *
198 * NOTE: PLEASE DO NOT USE THE DATA PROVIDED IN WEBHOOK DIRECTLY, AS HACKER COULD PASS IN FAKE DATA. IT IS VERY IMPORTANT THAT YOU RETRIEVE THE ID AND MAKE A SEPARATE CALL TO PAYPAL API.
199 *
200 * @deprecated Please use `VerifyWebhookSignature->post()` instead.
201 *
202 * @param string $body
203 * @param ApiContext $apiContext
204 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
205 * @return WebhookEvent
206 * @throws \InvalidArgumentException if input arguments are incorrect, or Id is not found.
207 * @throws PayPalConnectionException if any exception from PayPal APIs other than not found is sent.
208 */
209 public static function validateAndGetReceivedEvent($body, $apiContext = null, $restCall = null)
210 {
211 if ($body == null | empty($body)){
212 throw new \InvalidArgumentException("Body cannot be null or empty");
213 }
214 if (!JsonValidator::validate($body, true)) {
215 throw new \InvalidArgumentException("Request Body is not a valid JSON.");
216 }
217 $object = new WebhookEvent($body);
218 if ($object->getId() == null) {
219 throw new \InvalidArgumentException("Id attribute not found in JSON. Possible reason could be invalid JSON Object");
220 }
221 try {
222 return self::get($object->getId(), $apiContext, $restCall);
223 } catch(PayPalConnectionException $ex) {
224 if ($ex->getCode() == 404) {
225 // It means that the given webhook event Id is not found for this merchant.
226 throw new \InvalidArgumentException("Webhook Event Id provided in the data is incorrect. This could happen if anyone other than PayPal is faking the incoming webhook data.");
227 }
228 throw $ex;
229 }
230 }
231
232 /**
233 * Retrieves the Webhooks event resource identified by event_id. Can be used to retrieve the payload for an event.
234 *
235 * @param string $eventId
236 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
237 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
238 * @return WebhookEvent
239 */
240 public static function get($eventId, $apiContext = null, $restCall = null)
241 {
242 ArgumentValidator::validate($eventId, 'eventId');
243 $payLoad = "";
244 $json = self::executeCall(
245 "/v1/notifications/webhooks-events/$eventId",
246 "GET",
247 $payLoad,
248 null,
249 $apiContext,
250 $restCall
251 );
252 $ret = new WebhookEvent();
253 $ret->fromJson($json);
254 return $ret;
255 }
256
257 /**
258 * Resends a webhook event notification, by ID. Any pending notifications are not resent.
259 *
260 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
261 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
262 * @return WebhookEvent
263 */
264 public function resend($apiContext = null, $restCall = null)
265 {
266 ArgumentValidator::validate($this->getId(), "Id");
267 $payLoad = "";
268 $json = self::executeCall(
269 "/v1/notifications/webhooks-events/{$this->getId()}/resend",
270 "POST",
271 $payLoad,
272 null,
273 $apiContext,
274 $restCall
275 );
276 $this->fromJson($json);
277 return $this;
278 }
279
280 /**
281 * Lists webhook event notifications. Use query parameters to filter the response.
282 *
283 * @param array $params
284 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
285 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
286 * @return WebhookEventList
287 */
288 public static function all($params, $apiContext = null, $restCall = null)
289 {
290 ArgumentValidator::validate($params, 'params');
291 $payLoad = "";
292 $allowedParams = array(
293 'page_size' => 1,
294 'start_time' => 1,
295 'end_time' => 1,
296 'transaction_id' => 1,
297 'event_type' => 1,
298 );
299 $json = self::executeCall(
300 "/v1/notifications/webhooks-events" . "?" . http_build_query(array_intersect_key($params, $allowedParams)),
301 "GET",
302 $payLoad,
303 null,
304 $apiContext,
305 $restCall
306 );
307 $ret = new WebhookEventList();
308 $ret->fromJson($json);
309 return $ret;
310 }
311
312 }
313