Skip to content

Commit 748c274

Browse files
scotttrinhscotttrinh
committed
Add webhook configuration guide
1 parent 1941522 commit 748c274

File tree

1 file changed

+166
-27
lines changed

1 file changed

+166
-27
lines changed

‎docs/guides/auth/index.rst‎

Lines changed: 166 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,118 @@ To configure via query or script:
162162
};
163163
164164
165+
Configuring webhooks
166+
====================
167+
168+
The auth extension supports sending webhooks for a variety of auth events. You
169+
can use these webhooks to, for instance, send a fully customized email for
170+
email verification, or password reset instead of our built-in email
171+
verification and password reset emails. You could also use them to trigger
172+
analytics events, start an email drip campaign, create an audit log, or
173+
trigger other side effects in your application.
174+
175+
.. note::
176+
177+
We send webhooks with no durability or reliability guarantees, so you should
178+
always provide a mechanism for retrying delivery of any critical events,
179+
such as email verification and password reset. We detail how to resend these
180+
events in the relevant sections on the various authentication flows.
181+
182+
183+
Here are the webhooks that are currently supported:
184+
185+
.. list-table::
186+
:header-rows: 1
187+
:widths: 30 70
188+
189+
* - Event
190+
- Payload
191+
* - ``IdentityCreated``
192+
- | - ``event_type``: ``"IdentityCreated"`` (``str``)
193+
| - ``event_id``: Unique event identifier (``str``)
194+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
195+
| - ``identity_id``: ID of created identity (``str``)
196+
* - ``IdentityAuthenticated``
197+
- | - ``event_type``: ``"IdentityAuthenticated"`` (``str``)
198+
| - ``event_id``: Unique event identifier (``str``)
199+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
200+
| - ``identity_id``: ID of authenticated identity (``str``)
201+
* - ``EmailFactorCreated``
202+
- | - ``event_type``: ``"EmailFactorCreated"`` (``str``)
203+
| - ``event_id``: Unique event identifier (``str``)
204+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
205+
| - ``identity_id``: Associated identity ID (``str``)
206+
| - ``email_factor_id``: ID of created email factor (``str``)
207+
* - ``EmailVerified``
208+
- | - ``event_type``: ``"EmailVerified"`` (``str``)
209+
| - ``event_id``: Unique event identifier (``str``)
210+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
211+
| - ``identity_id``: Associated identity ID (``str``)
212+
| - ``email_factor_id``: ID of verified email factor (``str``)
213+
* - ``EmailVerificationRequested``
214+
- | - ``event_type``: ``"EmailVerificationRequested"`` (``str``)
215+
| - ``event_id``: Unique event identifier (``str``)
216+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
217+
| - ``identity_id``: Associated identity ID (``str``)
218+
| - ``email_factor_id``: ID of email factor to verify (``str``)
219+
| - ``verification_token``: Token for verification (``str``)
220+
* - ``PasswordResetRequested``
221+
- | - ``event_type``: ``"PasswordResetRequested"`` (``str``)
222+
| - ``event_id``: Unique event identifier (``str``)
223+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
224+
| - ``identity_id``: Associated identity ID (``str``)
225+
| - ``email_factor_id``: ID of email factor (``str``)
226+
| - ``reset_token``: Token for password reset (``str``)
227+
* - ``MagicLinkRequested``
228+
- | - ``event_type``: ``"MagicLinkRequested"`` (``str``)
229+
| - ``event_id``: Unique event identifier (``str``)
230+
| - ``timestamp``: ISO 8601 timestamp (``datetime``)
231+
| - ``identity_id``: Associated identity ID (``str``)
232+
| - ``email_factor_id``: ID of email factor (``str``)
233+
| - ``magic_link_token``: Token for magic link (``str``)
234+
| - ``magic_link_url``: Complete URL for magic link (``str``)
235+
236+
You can configure webhooks with the UI or via query.
237+
238+
.. code-block:: edgeql
239+
240+
CONFIGURE CURRENT BRANCH INSERT
241+
ext::auth::WebhookConfig {
242+
url := 'https://example.com/auth/webhook',
243+
events := {
244+
ext::auth::WebhookEvent.EmailVerificationRequested,
245+
ext::auth::WebhookEvent.PasswordResetRequested,
246+
}
247+
};
248+
249+
.. note::
250+
251+
URLs must be unique across all webhooks configured for each branch. If you want
252+
to send multiple events to the same URL, you can do so by adding multiple
253+
``ext::auth::WebhookEvent`` values to the ``events`` set.
254+
255+
256+
Configuring SMTP
257+
================
258+
259+
For email-based factors, you can configure SMTP to allow the extension to send
260+
emails on your behalf. You should either configure SMTP, or webhooks for the
261+
relevant events.
262+
263+
Here is an example of configuring SMTP for local development, using something
264+
like `Mailpit <https://mailpit.axllent.org/docs/>`__.
265+
266+
.. code-block:: edgeql
267+
268+
CONFIGURE CURRENT BRANCH INSERT cfg::SMTPProviderConfig {
269+
sender := 'hello@example.com',
270+
host := 'localhost',
271+
port := <int32>1025,
272+
security := 'STARTTLSOrPlainText',
273+
validate_certs := false,
274+
};
275+
276+
165277
Enabling authentication providers
166278
=================================
167279

@@ -204,7 +316,11 @@ To enable via query or script:
204316

205317
If you use the Email and Password provider, in addition to the
206318
``require_verification`` configuration, you’ll need to configure SMTP to allow
207-
EdgeDB to send email verification and password reset emails on your behalf.
319+
EdgeDB to send email verification and password reset emails on your behalf or
320+
set up webhooks for the relevant events:
321+
322+
- ``ext::auth::WebhookEvent.EmailVerificationRequested``
323+
- ``ext::auth::WebhookEvent.PasswordResetRequested``
208324

209325
Here is an example of setting a local SMTP server, in this case using a
210326
product called `Mailpit <https://mailpit.axllent.org/docs/>`__ which is
@@ -220,6 +336,19 @@ great for testing in development:
220336
validate_certs := false,
221337
};
222338
339+
Here is an example of setting up webhooks for the email verification and
340+
password reset events:
341+
342+
.. code-block:: edgeql
343+
344+
CONFIGURE CURRENT BRANCH INSERT ext::auth::WebhookConfig {
345+
url := 'https://example.com/auth/webhook',
346+
events := {
347+
ext::auth::WebhookEvent.EmailVerificationRequested,
348+
ext::auth::WebhookEvent.PasswordResetRequested,
349+
}
350+
};
351+
223352
224353
OAuth
225354
-----
@@ -349,8 +478,8 @@ Magic link
349478
Magic link offers only one setting: ``token_time_to_live``. This determines how
350479
long after sending the magic link is valid.
351480

352-
Since magic links rely on email, you must also configure SMTP. For local
353-
testing, you can use the same method used for SMTP previously for
481+
Since magic links rely on email, you must also configure SMTP or webhooks. For
482+
local testing, you can use the same method used for SMTP previously for
354483
:ref:`the email and password provider <ref_guide_auth_overview_email_password>`.
355484

356485
Here is an example of setting a local SMTP server, in this case using a
@@ -359,20 +488,24 @@ great for testing in development:
359488

360489
.. code-block:: edgeql
361490
362-
CONFIGURE CURRENT DATABASE SET
363-
ext::auth::SMTPConfig::sender := 'hello@example.com';
364-
365-
CONFIGURE CURRENT DATABASE SET
366-
ext::auth::SMTPConfig::host := 'localhost';
491+
CONFIGURE CURRENT BRANCH INSERT cfg::SMTPProviderConfig {
492+
sender := 'hello@example.com',
493+
host := 'localhost',
494+
port := <int32>1025,
495+
security := 'STARTTLSOrPlainText',
496+
validate_certs := false,
497+
};
367498
368-
CONFIGURE CURRENT DATABASE SET
369-
ext::auth::SMTPConfig::port := <int32>1025;
499+
Here is an example of setting up webhooks for the magic link events:
370500

371-
CONFIGURE CURRENT DATABASE SET
372-
ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText';
501+
.. code-block:: edgeql
373502
374-
CONFIGURE CURRENT DATABASE SET
375-
ext::auth::SMTPConfig::validate_certs := false;
503+
CONFIGURE CURRENT BRANCH INSERT ext::auth::WebhookConfig {
504+
url := 'https://example.com/auth/webhook',
505+
events := {
506+
ext::auth::WebhookEvent.MagicLinkRequested,
507+
}
508+
};
376509
377510
378511
WebAuthn
@@ -393,8 +526,8 @@ WebAuthn
393526

394527
.. note::
395528

396-
You will need to configure SMTP. For local testing, you can use Mailpit as
397-
described in :ref:`the email/password section
529+
You will need to configure SMTP or webhooks. For local testing, you can use
530+
Mailpit as described in :ref:`the email/password section
398531
<ref_guide_auth_overview_email_password>`.
399532

400533
.. note::
@@ -410,20 +543,24 @@ great for testing in development:
410543

411544
.. code-block:: edgeql
412545
413-
CONFIGURE CURRENT DATABASE SET
414-
ext::auth::SMTPConfig::sender := 'hello@example.com';
415-
416-
CONFIGURE CURRENT DATABASE SET
417-
ext::auth::SMTPConfig::host := 'localhost';
546+
CONFIGURE CURRENT BRANCH INSERT cfg::SMTPProviderConfig {
547+
sender := 'hello@example.com',
548+
host := 'localhost',
549+
port := <int32>1025,
550+
security := 'STARTTLSOrPlainText',
551+
validate_certs := false,
552+
};
418553
419-
CONFIGURE CURRENT DATABASE SET
420-
ext::auth::SMTPConfig::port := <int32>1025;
554+
Here is an example of setting up webhooks for the WebAuthn events:
421555

422-
CONFIGURE CURRENT DATABASE SET
423-
ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText';
556+
.. code-block:: edgeql
424557
425-
CONFIGURE CURRENT DATABASE SET
426-
ext::auth::SMTPConfig::validate_certs := false;
558+
CONFIGURE CURRENT BRANCH INSERT ext::auth::WebhookConfig {
559+
url := 'https://example.com/auth/webhook',
560+
events := {
561+
ext::auth::WebhookEvent.EmailVerificationRequested,
562+
}
563+
};
427564
428565
429566
Integrating your application
@@ -451,6 +588,8 @@ Select your method for detailed configuration:
451588
built_in_ui
452589
email_password
453590
oauth
591+
magic_link
592+
webauthn
454593

455594

456595
Example usage

0 commit comments

Comments
 (0)