diff --git a/docs/glossary/linked-account-object.mdx b/docs/glossary/linked-account-object.mdx
index cf7e1954a..d4f0e944f 100644
--- a/docs/glossary/linked-account-object.mdx
+++ b/docs/glossary/linked-account-object.mdx
@@ -15,8 +15,11 @@ icon: "user"
}
```
-- `linked_user_origin_id` is the **id** of the user inside your system.
-- `alias` is the name of your system/company. It holds information about **user's data**
- that exist in your **own product**.
+- `id_linked_user` is the **id** of the user inside **our** system.
+- `linked_user_origin_id` is the **id** of the user inside **your** system.
+- `alias` is the name of your system/company.
+
+It holds information about **user's data**
+that exist in your **own product**.
The idea is to have a deep copy of all your user's information inside our own database.
diff --git a/docs/images/custom-oauth.png b/docs/images/custom-oauth.png
new file mode 100644
index 000000000..707ad191c
Binary files /dev/null and b/docs/images/custom-oauth.png differ
diff --git a/docs/images/webhooks.mp4 b/docs/images/webhooks.mp4
new file mode 100644
index 000000000..f4ddf5d87
Binary files /dev/null and b/docs/images/webhooks.mp4 differ
diff --git a/docs/recipes/add-custom-provider-creds.mdx b/docs/recipes/add-custom-provider-creds.mdx
index c5b0a6ebb..812ab95f3 100644
--- a/docs/recipes/add-custom-provider-creds.mdx
+++ b/docs/recipes/add-custom-provider-creds.mdx
@@ -1,5 +1,18 @@
---
-title: "Add Custom OAuth Credentials"
-description: "Use Magic Links to invite your users to grant you access to their data without a dedicated website. Create a full connection flow in just a few clicks. **No code required.**"
+title: "Manage Custom Connectors"
+description: "By default, all connectors use Panora's managed developer applications. You have the option to use your own custom apps."
icon: "gear-code"
----
\ No newline at end of file
+---
+
+
+ Before getting started, make sure you've created a custom oAuth application
+ inside your sofwtare's developer account.{" "}
+
+
+## How to add custom credentials for a connector ?
+
+Visit the _Manage Connectors_ [section](https://dashboard.panora.dev/configuration), choose the connector you wish to add credentials for and add your own credentials.
+
+
+ 
+
diff --git a/docs/recipes/catch-connection-token.mdx b/docs/recipes/catch-connection-token.mdx
index 763b91d08..897f6a96c 100644
--- a/docs/recipes/catch-connection-token.mdx
+++ b/docs/recipes/catch-connection-token.mdx
@@ -1,5 +1,258 @@
---
title: "Catch Connection Token"
-description: "Use Magic Links to invite your users to grant you access to their data without a dedicated website. Create a full connection flow in just a few clicks. **No code required.**"
+description: ""
icon: "webhook"
----
\ No newline at end of file
+---
+
+Before getting started, you must have set up the auth flow through [magic-link or using the embedded snippet](/quick-start).
+If you need to understand in depth these concepts, jump to the [magic-link](/recipes/share-magic-link) and [frontend widget](/recipes/embed-catalog) recipes.
+
+
+ You may need to follow first our [webhook](/webhooks/overview) guide so you
+ can understand quickly the next steps.
+
+# How to catch connection tokens ?
+
+A `connection_token` is created everytime a user connects an account to your platform.
+It is a field of the [Connection Object](/glossary/connection-object) that Panora sends as a payload data through a webhook when you listen to events tagged as `connection.created`.
+
+
+
+
+ We must listen to `connection.created` event.
+
+
+
+
+ ```javascript Node
+ // This example uses Express to receive webhooks
+ import express, { Request, Response } from 'express';
+ const app = express();
+ app.use(express.json());
+
+ // Match the raw body to content type application/json
+ // If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
+ app.post('/webhook', (request, response) => {
+ const event = request.body;
+
+ // Handle the event
+ switch (event.type) {
+ case 'connection.created':
+ const connectionObject = event.data;
+ // Then define and call a method to handle the successful connection creation.
+ // handleConnectionCreationSucceeded(connectionObject);
+ break;
+ default:
+ console.log(`Unhandled event type ${event.type}`);
+ }
+
+ // Return a response to acknowledge receipt of the event
+ response.json({
+ received: true
+ });
+ });
+
+ app.listen(8000, () => console.log('Running on port 8000'));
+ ```
+
+ ```python Python
+ import json
+ from django.http import HttpResponse
+
+ # Using Django
+ @csrf_exempt
+ def my_webhook_view(request):
+ event = request.body
+
+ # Handle the event
+ if event.type == 'connection.created':
+ connection_object = event.data
+ # Then define and call a method to handle the successful connection creation.
+ # handle_connection_creation_succeeded(connection_object)
+ else:
+ print('Unhandled event type {}'.format(event.type))
+
+ return HttpResponse(status=200)
+ ```
+
+
+ If you log `event.data`, you'll be able to check that it is a [Connetion Object](/glossary/connection-object). Hence, it contains an `id_linked_user`(more info [here](/glossary/linked-account-object)) which is helpful to attach it to your own end-user on your backend/db systems.
+
+
+ Register the webhook endpoint’s accessible URL using the _Webhooks_ [section](https://dashboard.panora.dev/configuration) or the API so Panora knows where to deliver events.
+
+ **Webhook URL format**
+
+ The URL format to register a webhook endpoint is:
+ ```
+ https:///
+ ```
+ For example, if your domain is `https://mycompanysite.com` and the route to your webhook endpoint is `@app.route('/panora_webhooks', methods=['POST'])`, specify `https://mycompanysite.com/panora_webhooks` as the Endpoint URL.
+
+ **Add a webhook endpoint**
+
+ Navigate to the _Configuration_ [section](https://dashboard.panora.dev/configuration) and head to the Webhooks tab.
+
+
+ **Register a webhook endpoint with the Panora API**
+
+ You can also programmatically create [webhook endpoints](/api-reference/webhook/add-webhook-metadata).
+
+ The following example creates an endpoint that notifies you when a connection is created.
+
+
+ ```shell Curl
+ curl --request POST \
+ --url https://api.panora.dev/webhook \
+ --header 'Authorization: Bearer ' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "url": "https://example.com/my/webhook/endpoint",
+ "description": "Receive Connection Creation Events",
+ "scope": [
+ "connection.created"
+ ]
+ }'
+ ```
+
+ ```ts Typescript
+ import { PanoraSDK } from '@panora/sdk-typescript';
+
+ const sdk = new PanoraSDK({ accessToken: MY_API_KEY});
+
+ const input = {
+ description: 'Receive Connection Creation Events',
+ scope: ['connection.created'],
+ url: 'https://example.com/my/webhook/endpoint',
+ };
+ const result = await sdk.webhook.createWebhookMetadata(input);
+ console.log(result);
+ ```
+
+ ```python Python
+ from panorasdk import PanoraSDK
+
+ sdk = PanoraSDK()
+
+ sdk.set_access_token("MY_API_KEY")
+
+ request_body = {
+ description: 'Receive Connection Creation Events',
+ scope: ['connection.created'],
+ url: 'https://example.com/my/webhook/endpoint',
+ }
+
+ results = sdk.webhook.create_webhook_metadata(
+ request_input = request_body,
+ )
+
+ print(results)
+ ```
+
+
+
+
+ We highly recommend you secure your integration by ensuring your handler verifies that all webhook requests are generated by Panora. You can choose to verify webhook signatures using our official libraries or verify them manually.
+
+ **Verify webhook signatures with official library**
+
+ We recommend using our official libraries to verify signatures. You perform the verification by providing the event payload, the `Panora-Signature` header, and the endpoint’s secret. If verification fails, you get an error.
+
+
+ ```javascript Node
+ import express, { Request, Response } from 'express';
+ import { PanoraSDK } from '@panora/sdk-typescript';
+
+ // Set your api key
+ // See your keys here: https://dashboard.panora.dev/api-keys
+ const panora = new PanoraSDK({ accessToken: "MY_API_KEY" });
+
+ // Find your endpoint's secret in your webhook settings in the Config Page
+ const endpointSecret = 'whsec_...';
+
+ // This example uses Express to receive webhooks
+ const app = express();
+
+ app.use(express.json());
+
+ // Match the raw body to content type application/json
+ app.post('/webhook', async (request, response) => {
+ const sig = request.headers['panora-signature'];
+
+ let event;
+
+ try {
+ // Verifies that the event comes from Panora and not from malicious sender
+ event = await panora.webhook.verifyEvent(request.body, sig, endpointSecret);
+ }
+ catch (err) {
+ response.status(400).send(`Webhook Error: ${err.message}`);
+ }
+
+ // Handle the event
+ switch (event.type) {
+ case 'connection.created':
+ const connectionObject = event.data;
+ // Then define and call a method to handle the successful connection creation.
+ // handleConnectionCreationSucceeded(connectionObject);
+ break;
+ default:
+ console.log(`Unhandled event type ${event.type}`);
+ }
+
+ // Return a response to acknowledge receipt of the event
+ response.json({received: true});
+ });
+
+ app.listen(8080, () => console.log('Running on port 8080'));
+ ```
+
+
+ ```python Python
+ from panorasdk import PanoraSDK
+ from django.http import HttpResponse
+
+ # Set your secret key.
+ # See your keys here: https://dashboard.panora.dev/api-keys
+ panora = PanoraSDK('YOUR_API_KEY')
+
+ # Find your endpoint's secret in your webhook settings in the Config Page
+ endpoint_secret = 'whsec_...'
+
+
+ # Using Django
+ @csrf_exempt
+ def my_webhook_view(request):
+ payload = request.body
+ sig_header = request.META['panora-signature']
+ event = None
+
+ try:
+ # Verifies that the event comes from Panora and not from malicious sender
+ event = panora.webhook.verify_event(
+ payload, sig_header, endpoint_secret
+ )
+ except ValueError as e:
+ # Invalid payload
+ print('Error parsing payload: {}'.format(str(e)))
+ return HttpResponse(status=400)
+
+ # Handle the event
+ if event.type == 'connection.created':
+ connection_object = event.data
+ # Then define and call a method to handle the successful connection creation.
+ # handle_connection_creation_succeeded(connection_object)
+ else:
+ print('Unhandled event type {}'.format(event.type))
+
+ return HttpResponse(status=200)
+ ```
+
+
+
+
+
diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx
index 41ade0025..f12bd8729 100644
--- a/docs/webhooks/overview.mdx
+++ b/docs/webhooks/overview.mdx
@@ -69,11 +69,11 @@ To enable webhook events, you need to register webhook endpoints. After you regi
# Handle the event
if event.type == 'crm.contact.created':
- contact_data = event.data
+ contact_data = event.data
# Then define and call a method to handle the successful contact creation.
# handle_contact_creation_succeeded(contact_data)
elif event.type == 'crm.company.created':
- company_data = event.data
+ company_data = event.data
# Then define and call a method to handle the successful company creation.
# handle_company_creation_succeeded(company_data)
# ... handle other event types
@@ -86,36 +86,30 @@ To enable webhook events, you need to register webhook endpoints. After you regi
- Register the webhook endpoint’s accessible URL using the _Webhooks_ section or the API so Panora knows where to deliver events.
-
+ Register the webhook endpoint’s accessible URL using the _Webhooks_ [section](https://dashboard.panora.dev/configuration) or the API so Panora knows where to deliver events.
+
**Webhook URL format**
-
+
The URL format to register a webhook endpoint is:
- ```
+ ```
https:///
```
For example, if your domain is `https://mycompanysite.com` and the route to your webhook endpoint is `@app.route('/panora_webhooks', methods=['POST'])`, specify `https://mycompanysite.com/panora_webhooks` as the Endpoint URL.
**Add a webhook endpoint**
- _insert video_
-
-
-
-
-
-
-
-
-
-
-
-
-
+ Navigate to the _Configuration_ [section](https://dashboard.panora.dev/configuration) and head to the Webhooks tab.
+
+
+
**Register a webhook endpoint with the Panora API**
-
+
You can also programmatically create [webhook endpoints](/api-reference/webhook/add-webhook-metadata).
-
+
The following example creates an endpoint that notifies you when a connection is created.
@@ -171,9 +165,9 @@ To enable webhook events, you need to register webhook endpoints. After you regi
We highly recommend you secure your integration by ensuring your handler verifies that all webhook requests are generated by Panora. You can choose to verify webhook signatures using our official libraries or verify them manually.
-
+
**Verify webhook signatures with official library**
-
+
We recommend using our official libraries to verify signatures. You perform the verification by providing the event payload, the `Panora-Signature` header, and the endpoint’s secret. If verification fails, you get an error.
@@ -263,11 +257,11 @@ To enable webhook events, you need to register webhook endpoints. After you regi
# Handle the event
if event.type == 'crm.contact.created':
- contact_data = event.data
+ contact_data = event.data
# Then define and call a method to handle the successful contact creation.
# handle_contact_creation_succeeded(contact_data)
elif event.type == 'crm.company.created':
- company_data = event.data
+ company_data = event.data
# Then define and call a method to handle the successful company creation.
# handle_company_creation_succeeded(company_data)
# ... handle other event types
@@ -279,4 +273,5 @@ To enable webhook events, you need to register webhook endpoints. After you regi
-
\ No newline at end of file
+
+