The application demonstrates the use of Queues (Kafka in case of this application - see KafkaHelper.php) to process webhooks events.
Please note that the Webhooks events are not sent in chronological order with respect to the creation time. Events might be sent in large numbers, for example when the user imports large number of contacts or deletes a large list of contacts.
Common webhook processing practice consists of few steps:
- Handle methods receive the request sent by the webook and immediately place payload on the queue handle.php
- Message consumer instance(s) is running in a separate process, typically on multiple nodes in a cloud, such as AWS сonsumer.php
- Consumer stores webhook events in the database potentially calling an API to get full record of the object that triggered the event
- This application uses MySQL, the methods working with the database can be seen in EventsRepository.php
- Other services/objects fetch the events data from the database sorted by timestamp of the event EventsRepository.php
Please see the documentation on Creating an app in HubSpot
This application uses MySQL database to store the events coming from Webhooks. There is a single events table:
create table if not exists events
(
id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
event_type VARCHAR(255),
object_id int default null,
event_id bigint default null,
occurred_at bigint default null,
propertyName varchar(255) default null,
propertyValue varchar(255) default null,
created_at datetime default CURRENT_TIMESTAMP
);
Please note that event_id sent by HubSpot needs to be stored as int
Make sure you have Docker Compose installed and you have Ngrok account.
- Copy .env.template to .env
- Paste your HUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET, HUBSPOT_APPLICATION_ID & HUBSPOT_DEVELOPER_API_KEY.
- Paste your NGROK_AUTHTOKEN (You can get it in your ngrok account)
The best way to run this project (with the least configuration), is using docker compose. Change to the webroot and start it
docker-compose up --build
Copy Ngrok url from console and designate this on your app's Auth settings page. Now you should now be able to navigate to that url and use the application.
Required redirect URL should look like https://***.ngrok-free.app/oauth/callback Every time the app is restarted you should update the redirect URL. Learn more.
If you are using Ngrok free plan and testing the application with large amount of import/deletions of Contacts you are likely to see Ngrok "Too Many Connections" error. This is caused by a large amount of weebhooks events being sent to Ngrok tunnel. To avoid it you can deploy sample applications on your server w/o Ngrok or upgrade to Ngrok Enterprise version
Required webhooks url should look like https://***.ngrok-free.app/webhooks/handle
Following Webhooks Setup guide please note:
- Every time the app is restarted you should update the webhooks url
- The app supports
contact.creation
andcontact.deletion
subscription types only - Subscription are paused by default. You need to activate them manually after creating
To help improve security, HubSpot webhooks are sent with signature so you can verify that it came from HubSpot. This sample application shows how to do that verification. You can read more about validation in general here: https://developers.hubspot.com/docs/api/webhooks/validating-requests. The source code for validating webhooks is at HubSpot\Utils\Webhooks and an usage example