Slack Notification Channel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/slack-notification-channel
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Laravel\SlackNotificationChannel\SlackServiceProvider"
   

2. Configure Slack Webhook: Add your Slack webhook URL to .env:

   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
   

3. First Notification: Create a notification class extending SlackMessage:

   use Laravel\SlackNotificationChannel\SlackMessage;
   
   class OrderShipped extends SlackMessage
   {
       public function toSlack($notifiable)
       {
           return [
               'text' => 'Order #'.$this->order->id.' has shipped!',
               'blocks' => [
                   [
                       'type' => 'section',
                       'text' => [
                           'type' => 'mrkdwn',
                           'text' => '*Order Shipped* :rocket:'
                       ]
                   ]
               ]
           ];
       }
   }
   

4. Send Notification:

   use App\Notifications\OrderShipped;
   
   $user = User::find(1);
   $user->notify(new OrderShipped($order));
   

Key First Use Cases

• Alerts: Send incident notifications to a #alerts channel.
• User Actions: Notify admins when users complete critical actions (e.g., account creation).
• Scheduled Tasks: Dispatch Slack messages from Laravel’s schedule.

Implementation Patterns

Core Workflows

1. Basic Message Sending: Use SlackMessage for simple text or block-based messages. Leverage Laravel’s Notification facade:

   Notification::route('slack', $webhookUrl)->notify(new OrderShipped($order));
   

2. Rich Interactions:

   • Blocks: Use Slack’s Block Kit Builder to design interactive messages.

     public function toSlack($notifiable)
     {
         return [
             'blocks' => [
                 ['type' => 'section', 'text' => ['type' => 'mrkdwn', 'text' => 'Confirm action?']],
                 ['type' => 'actions', 'elements' => [
                     ['type' => 'button', 'text' => ['type' => 'plain_text', 'text' => 'Approve'], 'value' => 'approve'],
                     ['type' => 'button', 'text' => ['type' => 'plain_text', 'text' => 'Reject'], 'value' => 'reject']
                 ]]
             ]
         ];
     }
     

   • Attachments: For legacy Slack attachments (deprecated but supported):

     return [
         'attachments' => [
             [
                 'title' => 'Order Details',
                 'fields' => [
                     ['title' => 'ID', 'value' => $this->order->id, 'short' => true],
                     ['title' => 'Status', 'value' => 'Shipped', 'short' => true]
                 ]
             ]
         ]
     ];
     

3. Threaded Replies: Reply to a specific Slack message using thread_ts:

   public function toSlack($notifiable)
   {
       return [
           'text' => 'Follow-up message',
           'thread_ts' => '1234567890.000123' // Timestamp of parent message
       ];
   }
   

4. Conditional Logic: Skip notifications based on conditions:

   public function via($notifiable)
   {
       return $this->shouldSend() ? ['slack'] : [];
   }
   
   protected function shouldSend()
   {
       return config('app.env') === 'production';
   }
   

Integration Tips

• Queue Notifications: Use Laravel queues to avoid blocking HTTP requests:

  $user->routeNotificationFor('slack', $webhookUrl)->notify(new OrderShipped($order));
  

  Configure queue in .env:

  QUEUE_CONNECTION=database
  

• Dynamic Webhook URLs: Store webhook URLs in the database and fetch them dynamically:

  $notifiable->routeNotificationFor('slack', function ($notifiable) {
      return $notifiable->slackWebhookUrl;
  });
  

• Testing: Use SlackWebhookChannel with a mock webhook URL in tests:

  $this->actingAs($user)
       ->notify(new OrderShipped($order))
       ->assertSentToSlack(function ($message) {
           return $message['text'] === 'Order #123 shipped!';
       });
  

Gotchas and Tips

Common Pitfalls

1. Webhook URL Validation:

   • Ensure the Slack webhook URL is correct and the bot/app has permissions to post messages.
   • Debug Tip: Check Slack’s "Incoming Webhooks" configuration for the workspace.

2. Block Kit Validation:

   • Slack’s Block Kit Builder enforces strict JSON schema. Use the Block Kit Builder to validate your blocks before implementation.
   • Error Handling: Slack returns HTTP 400 for invalid payloads. Log the response:

     try {
         $this->send($notifiable, $message);
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         \Log::error('Slack notification failed:', ['response' => $e->getResponse()->getBody()]);
     }
     

3. Rate Limiting:

   • Slack imposes rate limits. Queue notifications to avoid hitting limits during spikes.
   • Workaround: Implement exponential backoff in your queue worker.

4. Threading Issues:

   • If thread_ts is invalid, Slack ignores the message. Always validate timestamps before sending.
   • Fix: Store the parent message’s ts in your database and retrieve it when replying.

5. Environment-Specific Config:

   • Avoid hardcoding webhook URLs. Use .env or database-driven configurations:

     SLACK_WEBHOOK_URL=${APP_ENV === 'production' ? 'prod_url' : 'dev_url'}
     

Debugging Tips

• Log Payloads: Override buildJsonPayload to log the final payload:

  public function buildJsonPayload($notifiable, array $message)
  {
      \Log::debug('Slack payload:', $message);
      return parent::buildJsonPayload($notifiable, $message);
  }
  

• Slack API Responses: Inspect the raw response from Slack:

  $response = $this->send($notifiable, $message);
  \Log::debug('Slack response:', $response->getBody());
  

• Block Kit Builder URL: Generate a URL to pre-fill the Block Kit Builder with your JSON:

  $message = new SlackMessage();
  $builderUrl = $message->getBlockKitBuilderUrl($payload);
  // Open $builderUrl in your browser to validate blocks.
  

Extension Points

1. Custom Slack Clients: Extend SlackWebhookChannel to use a custom HTTP client:

   use Laravel\SlackNotificationChannel\SlackWebhookChannel;
   use GuzzleHttp\Client;
   
   class CustomSlackChannel extends SlackWebhookChannel
   {
       protected function sendThroughSlack($notifiable, array $message)
       {
           $client = new Client(['timeout' => 30]);
           return $client->post($this->url, ['json' => $message]);
       }
   }
   

2. Dynamic Message Modification: Override toSlack to modify messages based on the notifiable:

   public function toSlack($notifiable)
   {
       $message = parent::toSlack($notifiable);
       $message['text'] .= " (User: {$notifiable->name})";
       return $message;
   }
   

3. Slack Actions Handling: Use Slack’s Events API to handle interactive components (buttons, selects). Example:

   // In your event listener for Slack actions
   if ($payload['actions'][0]['name'] === 'approve') {
       $this->handleApproval($payload['user']['id']);
   }
   

4. Multi-Channel Notifications: Send to multiple Slack channels by routing:

   $user->routeNotificationFor('slack', [
       'alerts' => 'https://hooks.slack.com/alerts',
       'general' => 'https://hooks.slack.com/general'
   ])->notify(new OrderShipped($order));
   

   Then override toSlack to conditionally format messages per channel:

   public function toSlack($notifiable,