Slack Events: Handling the URL Verification Event
Tags: python, webdev
Published: 2023-08-20 21:52:24

## Overview

This process had quite a few gotchas that I missed during implementation for Slack's URL Verification process for setting up an events webhook.

*I work for [Akkio](https://akkio.com), where I'm building out a no-code predictive AI platform. If you're looking to harness the power of AI without needing a data scientist, give us a try!*

## What does the endpoint expect?

The request expects a few things.

- The endpoint returns the provided challenge value either as  plaintext or as a `{ "challenge": "..." }` JSON value. Make sure you set the `Content-Type` header accordingly.
- Return a 200, not a 201 or something similar.
- The request is a POST, not a GET.

The main thing I misunderstood was that the `url_verification` event is *not* wrapped in an outer event like the rest of them. It's just three attributes in a single JSON object, nothing nested.

## Final Implementation

I'm using FastAPI, a prominent REST API framework for Python. You can likely extrapolate the general solution to whatever you're using.

Here's our actual code. Treat it all as pseudocode that may require minor changes, especially if you're translating across platforms.

The main controller:

```python
from fastapi.responses import PlainTextResponse
router = fastapi.APIRouter(prefix="/events")
import slack_app.events.models as SlackEventModels

@router.post(
    "",
    description="Slack Webhook Handler. Used to do things like respond to users that mention the ap.",
    status_code=200,
    tags=["slack", "webhooks"],
    response_class=PlainTextResponse
)
async def _handle_slack_events(request: fastapi.Request) -> Any:
    try:
        # Special case for one-time verification handleshake; Slack has you use the deprecated verification token for
        # this rather than the new signing method
        verification_body = SlackEventModels.VerificationHandshakeEvent(**await request.json())
        if verification_body.token != SETTINGS.SLACK_VERIFICATION_TOKEN:
            raise fastapi.HTTPException(status_code=401, detail="Invalid Slack Verification Token")
        return PlainTextResponse(verification_body.challenge, headers={"Content-Type": "text/plain"})
    except pydantic.ValidationError:
        # Just means it isn't a verification handshake; there are probably cleaner ways to handle, but this works fine
        pass
```

The referenced payload body definition we validate against:

```python
class VerificationHandshakeEvent(pydantic_config.BaseConfig):
    type: Literal["url_verification"]
    token: str # Slack legacy verification token; we use modern version and ignore this
    challenge: str
```

There's a bit of syntactic sugar, especially with the inheritance from a Pydantic class, but it's ultimately just a `type` field that'll always be `url_verification`, a `token` field that will be the *legacy* validation token that you get when creating a Slack app, and a *challenge* value that you're expected to return as plaintext.

## Conclusion

Hope you enjoyed! If I saved you some time and you'd like to support my work, check out my [Sponsors](https://github.com/sponsors/andenacitelli) page on GitHub.